Skip to main content

​
Verification Checklist

After integrating Sec0, confirm each layer is working:

​
Instrumentation

  • initializeSec0App() or loadStandardConfig() completes without errors
  • Decorated methods execute and return results normally
  • Audit files appear in the configured appenderDir

​
Middleware

  • sec0SecurityMiddleware(options)(server) wraps without errors
  • Tool calls succeed and audit envelopes are written to sec0.dir
  • Registry freeze is active (registering new tools after wrapping throws)

​
Gateway

  • startGatewayServer() binds to the configured port
  • POST /mcp/:server/:tool@version returns valid responses
  • Response headers include x-trace-id and x-span-id
  • Audit envelopes are written for each gateway call

​
Adaptive Approvals

  • Policy includes security.side_effects.human_escalation for the intended scope
  • Policy includes security.side_effects.approve_high_risk: true
  • enforcement.escalate_on is set (or omitted so it falls back to enforcement.deny_on)
  • Denied responses include escalation_id and escalation_status when escalation is created
  • Audit envelopes include escalation_id for escalated denials

​
Audit Output

Check your configured audit directory for daily-rotated files: 
ls -la .sec0/audit-*.ndjson
Each line is a valid JSON envelope: 
head -1 .sec0/audit-2026-02-06.ndjson | jq .

​
Common Errors

​
[sec0] Config file not found

Cause: sec0.config.yaml is missing or the path is incorrect. Fix: Ensure the file exists and the path is correct: 
ls -la sec0.config.yaml

​
[sec0] localDir is required

Cause: Missing localDir in configuration or controlPlane.sec0Dir in standard config. Fix: Add an absolute path: 
controlPlane:
  sec0Dir: /var/sec0-data

​
[sec0] localSignerPath is required

Cause: Missing or invalid signing key path. Fix:
  1. Generate a key:
mkdir -p .sec0/keys
openssl rand -base64 32 > .sec0/keys/ed25519.key
  1. Set the key path in config:
controlPlane:
  localSignerPath: ./.sec0/keys/ed25519.key

​
[sec0] Signing key file not found

Cause: The key file doesn’t exist at the configured path. Fix: Verify the file exists and has proper permissions: 
ls -la ./.sec0/keys/ed25519.key
# Should be readable by the Node.js process

​
[sec0] No hop configuration found for "ClassName.method"

Cause: The decorator can’t find a matching entry in app.hops. Fix: Add the hop entry to sec0.config.yaml: 
app:
  hops:
    ClassName.method:
      type: agent
      nodeId: my-agent
      agentName: my-agent
      agentVersion: "1.0.0"

​
[sec0] app.environment must be dev, staging, or prod

Cause: Invalid environment value. Fix: Set app.environment to one of dev, staging, or prod.

​
Control Plane Errors

  • API key validation failed: Verify your SEC0_API_KEY is valid and the control plane is reachable
  • controlPlaneUrl could not be resolved: Set SEC0_CONTROL_PLANE_URL environment variable or configure controlPlane.apiBaseUrl
  • Policy fetch fails: Ensure auth.apiKey or auth.bearerToken is set when using control-plane policy source

​
Gateway Errors

  • audit.append must be a function: Pass a valid Sec0Appender instance
  • quotas adapter required: Use InMemoryAdapter for development
  • Missing x-idempotency-key: The gateway requires this header on all requests

​
Approvals Errors

  • no_approvers_configured: Human review is required, but no reviewer group resolved for this request.
  • Frequent timeout decisions: Increase reviewer coverage or adjust strategy/quorum values in human_escalation.
  • Unexpected approvals/rejections: Re-check required_roles, veto_roles, and timeout_action in policy.
  • Missing escalation_id on denied responses: Verify approve_high_risk is enabled and the denial reason is included in enforcement.escalate_on (or enforcement.deny_on when escalate_on is not set).

​
Middleware Errors

  • REGISTRY_FROZEN: Cannot register new tools after wrapping. Register all tools before calling sec0SecurityMiddleware(options)(server)
  • HANDLER_SWAP: A tool handler was reassigned after wrapping. This is blocked for integrity
  • Cannot read properties of undefined (reading 'serviceName'): otel config is missing. Include otel.endpoint, otel.serviceName, and otel.environment in middleware options.

​
Environment Variables

VariablePurpose
SEC0_API_KEYAPI key for control plane authentication
SEC0_CONTROL_PLANE_URLOverride control plane base URL
SEC0_ESCALATION_TIMEOUT_MSTimeout (ms) for escalation create calls
SEC0_SIGNER_KEY_DIRSComma-separated allowed key directories for LocalDevSigner.fromKeyRef
SVC_TOKENService token for gateway auth

​
Debug Tips

​
Enable Debug Logging

sec0SecurityMiddleware({
  // ...
  runtime: {
    debug: {
      policySync: true,
      sast: true,
      dast: true,
    },
  },
})(server);

​
Inspect Audit Envelopes

# View latest entries
tail -5 .sec0/audit-$(date +%Y-%m-%d).ndjson | jq .

# Check for deny decisions
grep '"deny"' .sec0/audit-*.ndjson | jq .

# Count findings
grep 'agent_guard_findings' .sec0/audit-*.ndjson | wc -l

​
Verify Signing

import { LocalDevSigner, canonicalize, fromBase64 } from "sec0-sdk/signer";

const signer = LocalDevSigner.fromKeyRef("file://./.sec0/keys/ed25519.key");
const envelope = { /* your envelope without the sig field */ };
const msg = Buffer.from(canonicalize(envelope));
const ok = signer.verify(msg, fromBase64(envelopeSig));
console.log("Signature valid:", ok);
If issues persist, cross-check your configuration against the reference pages: