Loading HoneyMesh...
Loading HoneyMesh...
Developer manual · Node Guard Free · experimental alpha
This guide takes a Node.js application from installation through source verification, policy simulation, local enforcement, and recovery. The public package is @network-decode/node-guard. It runs inside your application and does not require a HoneyMesh agent, license, account, or root access.
Examples use version 0.2.0-alpha.12. Pin that version: the npm latest tag may refer to an older alpha. Review the public source and release notes before upgrading.
Installed HoneyMesh Node Guard Tools from Ubuntu App Center? Start with the Snap command-line manual. That policy CLI is an older alpha and does not install this SDK into your app.
Use Node.js 20 or newer in one persistent process. The evaluated integrations are Express middleware and Next.js App Router Route Handlers running in the Node runtime. The SDK counts only security observations that your application explicitly records. It cannot determine whether a login failed, whether a webhook signature is valid, or who owns an IP address for you.
OBSERVE policy mode.This is application-level protection. It does not install a host firewall, attach XDP to the kernel, or exchange intelligence with other nodes. Treat this alpha as an evaluation component, not the sole control for a critical service.
Run these commands in your application repository. Commit the dependency lockfile and review the generated policy before connecting it to a live route.
node --version
npm install @network-decode/node-guard@0.2.0-alpha.12
npm ls @network-decode/node-guard
npx nodeguard init
npx nodeguard doctor nodeguard.policy.json
npx nodeguard policy validate nodeguard.policy.jsoninit creates nodeguard.policy.json in OBSERVE mode with restrictive file permissions and refuses to overwrite an existing file. doctor checks the local policy and environment, but source_trust: not checked means it cannot verify your reverse proxy or ingress configuration. That check is your responsibility.
For a source checkout, follow the developer setup. The package is Apache-2.0 licensed.
Source identity is the most important integration boundary. A client can supply its own X-Forwarded-For header. Trust a forwarded address only when the immediate socket peer is a proxy that you explicitly control and list by exact IP address. The bundled resolver rejects malformed forwarding chains; CIDR ranges are not accepted.
import { createTrustedSourceResolver } from "@network-decode/node-guard/trusted-source";
// Direct connection: use the socket peer; ignore untrusted forwarded headers.
const directSource = createTrustedSourceResolver({ trustedProxyIps: [] });
// Behind your own reverse proxy: replace this with its actual peer IP.
const proxiedSource = createTrustedSourceResolver({
trustedProxyIps: ["127.0.0.1"],
});
// For an Express request, call either resolver with the actual request.
// const sourceIp = proxiedSource(req);The loopback address above is an example, not a recommended universal proxy setting. Confirm the peer address in your deployment, account for every proxy hop, and test a spoofed forwarding header from an unlisted peer. Never take a source IP, user ID, tenant ID, or API key ID from an arbitrary request body.
The v1 policy matches one application, route, and reason code. This example observes repeated, application-verified authentication failures on a login route:
{
"schema_version": 1,
"policy_id": "auth-login-v1",
"application_id": "billing-api",
"mode": "OBSERVE",
"route_id": "auth.login",
"reason_code": "authentication_failure",
"window_seconds": 60,
"threshold": 2,
"action": "THROTTLE",
"restriction_seconds": 120
}| Field | Purpose |
|---|---|
schema_version | Set to 1 for the v1 policy contract. |
policy_id | Stable name for audit and comparison. |
application_id | Must match observations from this application. |
mode | OBSERVE reports a decision; ENFORCE can apply the configured action. |
route_id / reason_code | Only matching, verified observations count. |
window_seconds / threshold | How many matching observations within the rolling time window trigger a decision. |
action / restriction_seconds | THROTTLE or DENY and the temporary restriction duration if ENFORCE is active. |
These values are an example for a controlled test, not a recommended production threshold. Use your own normal-traffic evidence to select a window, threshold, action, and duration. Keep this file under change review; do not put secrets or private event data in it.
Call guard.record only after your application has actually verified the security event. An HTTP error status alone is not an authentication failure. Each observation needs a unique event ID, UTC timestamp, verified source IP, matching application and route IDs, reason code, and HTTP or HTTPS protocol.
import { randomUUID } from "node:crypto";
import { createPolicyGuardV1 } from "@network-decode/node-guard/policy-runtime";
const guard = createPolicyGuardV1({
policy,
canActOnSource: (ip) => !protectedSources.has(ip),
onDecision: (decision) => {
// Send a minimal, sanitized decision to your own monitoring system.
console.info(decision.action, decision.policy_id);
},
});
// Inside your application's verified failed-login branch:
guard.record({
schema_version: 1,
application_id: "billing-api",
event_id: randomUUID(),
observed_at: new Date().toISOString(),
route_id: "auth.login",
reason_code: "authentication_failure",
source_ip: verifiedSourceIp,
protocol: "HTTPS",
});protectedSources, policy, and verifiedSourceIp above are application-owned values. The exclusion callback is required in ENFORCE mode; maintain it with canonical IP addresses for management and other protected sources. The SDK normalizes eligible IPv6 addresses. A rejected record can report policy_mismatch, source_excluded, outside_window, capacity_exhausted, or duplicate_event. Capture those outcomes in your own monitoring without recording credentials, request bodies, or full private events.
The package includes synthetic observations that match the generated policy. Run a fixed-time simulation, then test sanitized cases from your own application: ordinary users, repeated failures, a control source, a protected source, mismatched routes, duplicate event IDs, and malformed client forwarding chains.
cp node_modules/@network-decode/node-guard/examples/auth-observations.json ./observations.json
npx nodeguard policy test nodeguard.policy.json observations.json --at 2026-11-03T18:00:00Z
npx nodeguard inspect nodeguard.policy.json
npx nodeguard policy diff nodeguard.policy.json proposed-policy.json
npx nodeguard policy compare nodeguard.policy.json proposed-policy.json observations.json --at 2026-11-03T18:00:00ZCreate proposed-policy.json yourself before running the last two commands. The bundled fixture should produce an OBSERVE decision and no live restriction. policy test, diff, and compare are offline review tools: they do not send requests or activate a policy. The v1 comparison does not itself model protected-source exemptions, so test those through your runtime integration too.
Use one guard instance for the process. Mount its middleware on the route you are evaluating, before the route handler. The adapter checks for an existing restriction; your handler must separately record a verified failure. The sketch below assumes your application already has credential verification and a known proxy topology.
import express from "express";
import policy from "./nodeguard.policy.json" with { type: "json" };
import { randomUUID } from "node:crypto";
import { createPolicyGuardV1 } from "@network-decode/node-guard/policy-runtime";
import { createExpressNodeGuard } from "@network-decode/node-guard/express";
import { createTrustedSourceResolver } from "@network-decode/node-guard/trusted-source";
const app = express();
app.use(express.json());
const getSource = createTrustedSourceResolver({ trustedProxyIps: [] });
const protectedSources = new Set(["127.0.0.1"]);
const guard = createPolicyGuardV1({
policy,
canActOnSource: (ip) => !protectedSources.has(ip),
});
app.post("/login", createExpressNodeGuard({
guard,
getVerifiedSourceIp: getSource,
}), async (req, res) => {
const verifiedSourceIp = getSource(req);
// Replace this with your application's real credential verification.
const valid = await verifyCredentials(req.body);
if (valid) return res.json({ ok: true });
guard.record({
schema_version: 1,
application_id: "billing-api",
event_id: randomUUID(),
observed_at: new Date().toISOString(),
route_id: "auth.login",
reason_code: "authentication_failure",
source_ip: verifiedSourceIp,
protocol: req.secure ? "HTTPS" : "HTTP",
});
return res.status(401).json({ error: "invalid credentials" });
});
// Add your normal error handler; source verification errors reach next(error).verifyCredentials is an application function that you must implement; the example does not supply authentication. If TLS ends at a trusted proxy, determine the protocol from that trusted ingress rather than treating an arbitrary forwarding header as proof. Do not set Express trust proxy broadly as a substitute for verified source handling. Under ENFORCE, the middleware returns 429 for THROTTLE or 403 for DENY with Retry-After. In OBSERVE it allows requests through.
A Web Request does not expose a trustworthy socket peer by itself. Supply getVerifiedSourceIp from a deployment-owned ingress boundary. Do not use an unverified X-Forwarded-For header. Initialize one guard in a persistent Node process, check for a restriction before handling the request, and record only a verified application event afterward.
import { createNextRouteGuard } from "@network-decode/node-guard/next-route";
// guard and ingress are application-owned, initialized in a persistent process.
const check = createNextRouteGuard({
guard,
getVerifiedSourceIp: (request) => ingress.getVerifiedSourceIp(request),
});
export async function POST(request) {
const restriction = await check(request);
if (restriction) return restriction;
// Authenticate, handle the request, and record only verified failures.
return Response.json({ ok: true });
}This is an adapter sketch, not a complete Route Handler: define guard, ingress, and your application logic in your own project. If source verification fails, the adapter returns 503 with Cache-Control: no-store. Use the Node runtime, not Edge. With Next.js Cache Components enabled, omit a runtime export. On serverless or multi-worker deployments, use OBSERVE only until a qualified shared-state design exists. See the upstream Route Handler guide.
canActOnSource so management and other protected sources cannot be restricted. Test it at runtime; the offline comparison does not cover this exemption.mode to ENFORCE, deploy the reviewed policy, and restart the application. Try a noncritical test source first.guard.release(verifiedIp) in the affected process. For a broad rollback, restore OBSERVE and restart. A restart also clears all in-memory restrictions.Never expose release as an unauthenticated public endpoint. If you run multiple workers, release must reach each affected worker; the alpha has no shared state or durable audit store. Keep your own sanitized monitoring and incident notes.
Version alpha.12 also includes tools for reviewing synthetic policies and observations locally. They do not deploy an enforcement rule.
npx nodeguard builder templates
npx nodeguard builder init my-security-tool
npx nodeguard builder check my-security-tool
npx nodeguard builder review my-security-tool --output my-review.json
npx nodeguard replay nodeguard.policy.json observations.json --at 2026-11-03T18:00:00Z --redact
npx nodeguard export nodeguard.policy.json --output sanitized-policy.jsonbuilder init creates a synthetic project and refuses to overwrite one; review writes a private local report. replay reconstructs a simulated timeline, not the state of your running app. export writes validated policy fields, not observations, and refuses to overwrite a file. Keep real customer data and reports out of public source control.
Identity scopes v2 are a separate, experimental contract for application-verified identities. A source IP, user, tenant, and API key have different trust boundaries. Do not promote client-supplied IDs into verified identities or assume v1 policy behavior applies unchanged to v2.
source_trust: not checkedrecord, that the policy and event IDs match, the UTC timestamp is inside the window, the event ID is unique, and the threshold was reached. OBSERVE reports a decision but does not restrict.For a reproducible independent check, see the SDK's test guide. Report suspected security issues privately using the security policy.