Guardification documentation

#What is Guardification?

Guardification is a monitoring and passive-security platform for web apps. You install one npm package — @guardification/sdk — initialise it with a project key, and deploy. From then on the SDK reports requests, errors, a heartbeat and security signals to Guardification, which aggregates them into a live dashboard: a health score, traffic and latency, request-by-status, plain-English issues, and on-demand code scanning of your GitHub repo.

• Fail-open: the SDK can never crash or block your app — every path swallows its own errors.
• Async: events flush after the response, so users never wait on it.
• Report-only security: findings are surfaced, never blocked.

#How it works

1. 1
   Install the SDK and set one API key in your environment.
2. 2
   The SDK captures events — requests, errors, a heartbeat, security signals — and batches them.
3. 3
   It flushes to the ingest API (POST /api/ingest) authenticated by your hashed API key, after the response, with a short timeout.
4. 4
   Guardification aggregates raw events into hourly rollups and deduplicated issues.
5. 5
   The dashboard reads the aggregates and shows health, performance and security — live.

#Quick start (Next.js)

npm install @guardification/sdk

GUARDIFICATION_KEY=gdf_live_your_project_key_here

import { register } from "@guardification/sdk";

export function register() {
  register({ projectKey: process.env.GUARDIFICATION_KEY! });
}

Grab your key from Dashboard → Settings → API key. Other frameworks use a subpath import — see below. The in-app Integration page generates the exact snippets for your stack.

#Framework support

One SDK, ten idiomatic entry points. Each fails open and is tree-shakeable.

#SDK API

• register(config) — configure once on boot and emit a heartbeat (Next/Node).
• init(config) — configure without a heartbeat.
• withMonitor(handler) — wrap middleware to time + record every request.
• monitorRoute(handler) — wrap a route/handler (duration + status).
• onRequestError(err, req?) — record an exception (e.g. from Next's onRequestError).
• capture(event) / flush() — manual escape hatches.
• /react — GuardificationProvider, useRouteMonitor, useMonitorError, GuardificationErrorBoundary.
• /express, /hono, /vue, /svelte, /astro, /nuxt, /angular — framework adapters.

#The event model

Every event the SDK sends is one of four types:

• heartbeat — sent once on boot/mount so the dashboard confirms your install.
• request — route, method, status, durationMs (powers traffic, latency, status mix).
• error — message + metadata (powers issues and error rate).
• security — passive runtime security signals.

Raw events live in append-only time-series tables; the dashboard reads pre-aggregated hourly rollups, never the raw stream. Issues are deduplicated by project + category + route.

#Code scanning

Connect GitHub in Security → Code scanning, pick a repo and run a scan. Guardification analyses your source for the issues that lead to easy attacks:

• Leaked secrets & API keys (AWS keys, private keys, GitHub/Slack tokens, JWTs)
• SQL injection (string-concatenated / interpolated queries)
• Cross-site scripting (dangerouslySetInnerHTML, innerHTML, document.write)
• Command injection & eval()
• Disabled TLS verification & wildcard CORS
• Weak hashing (MD5 / SHA-1)
• Vulnerable npm dependencies (CVEs, via the OSV.dev advisory database)
• The OWASP Top Ten & CWE Top 25 (via the optional Semgrep worker)

By default a built-in scanner runs instantly via the GitHub API (no extra setup). For deeper analysis you can deploy the optional Semgrep worker. Re-scanning the same repo only reports newfindings — known issues aren't duplicated. Everything is report-only: findings are surfaced, never blocked.

#Configuration

#FAQ