Neuwerk

Roll Out A Policy With Audit Mode

Evaluate a new policy without enforcing its denies, review the results, and then promote it to enforce mode.

Use this guide when you want to test a policy before it starts blocking traffic.

The safe pattern is:

  1. write the policy with the relevant source group in audit mode
  2. confirm performance mode is enabled if you plan to use audit findings or wiretap
  3. generate representative traffic
  4. review audit evidence
  5. tighten the policy if needed
  6. promote the same source group to enforce

Do Not Confuse Source-Group Mode And Rule Mode

Source-group mode and per-rule mode do different things.

  • source-group mode: audit evaluates matching denies for that group but converts them into allow
  • per-rule mode: audit overrides an enforcing source group for that rule only

For rollout safety, start by changing the source-group mode.

Check Performance Mode First

The audit and wiretap APIs depend on performance mode. Verify the setting before starting your dry run:

GET /api/v1/settings/performance-mode

If it is disabled, enable it first with:

{
  "enabled": true
}

Write that body to:

PUT /api/v1/settings/performance-mode

Step 1: Write The Policy In Audit Mode

Use the same policy body you intend to enforce, but set the source group:

{
  "mode": "audit"
}

Write it to the singleton policy endpoint:

curl -sk \
  -H "Authorization: Bearer $NEUWERK_TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT \
  https://neuwerk.example/api/v1/policy \
  --data @policy.json

Step 2: Verify The Node Is Ready

After the write succeeds, check:

GET /ready
GET /api/v1/stats

This confirms the policy was accepted, compiled, and replayed locally.

Step 3: Generate Representative Traffic

Exercise the flows the policy is meant to allow and the flows it is meant to deny.

Be deliberate here:

  • use real client source IPs when possible
  • test both expected allows and expected denies
  • include DNS traffic if hostname policy is involved

Step 4: Review Audit Evidence

Use the evidence surfaces that fit the change:

  • GET /api/v1/audit/findings
  • GET /api/v1/dns-cache for hostname-policy validation
  • GET /api/v1/wiretap/stream for live confirmation

Audit findings are the most useful signal when they are available, because they show what the Neuwerk would have denied without turning the deny into an outage.

Step 5: Tighten The Policy

Common reasons to revise the policy before enforcement:

  • a source group is broader than intended
  • a hostname rule is missing
  • a deny rule needs higher priority than a broad allow
  • a destination or port matcher is too narrow or too broad

Revise the same singleton policy document and repeat the audit cycle until the results are clean enough to promote.

Step 6: Promote To Enforce

When you are ready, change only the source-group mode:

{
  "mode": "enforce"
}

Keep the rest of the policy unchanged unless you are intentionally revising it.

After promotion, verify:

GET /ready
GET /api/v1/stats
GET /api/v1/audit/findings

Warning

Moving a source group from audit to enforce changes the active behavior immediately. Promote narrow source groups first when the blast radius matters.

Next Steps