Neuwerk

Create Your First Policy

Start with hostname-aware policy in audit mode, then tighten it with TLS metadata before enforcing it.

This tutorial shows a safe first policy workflow:

  1. create a hostname-aware singleton policy through the management API
  2. start the source group in audit mode so traffic still flows while you verify the intent
  3. confirm that DNS policy and runtime state look correct
  4. optionally tighten the allow path with TLS metadata
  5. promote the source group to enforce when the observed behavior matches your intent

This tutorial assumes:

  • your node is already running
  • you have an admin bearer token
  • you know the management URL

If you do not yet have admin access, start with Get Admin Access.

Choose A Small First Policy

Start with one source group and one hostname allow rule. This shows the differentiator that Neuwerk exists to provide: explicit DNS-aware enforcement, not just static destination IP rules.

{
  "default_policy": "deny",
  "source_groups": [
    {
      "id": "office-users",
      "mode": "audit",
      "sources": {
        "cidrs": ["10.10.0.0/16"]
      },
      "default_action": "deny",
      "rules": [
        {
          "id": "allow-api-example-dns",
          "action": "allow",
          "match": {
            "dns_hostname": "^api\\.example\\.com$"
          }
        },
        {
          "id": "allow-api-example-https",
          "action": "allow",
          "match": {
            "proto": "tcp",
            "dst_ports": [443]
          }
        }
      ]
    }
  ]
}

Why start here:

  • the source population is explicit
  • the allowed destination is expressed as a hostname, not a fragile IP list
  • the default behavior is deny
  • source-group audit mode lets you observe the behavior before you block production traffic

Important detail: hostname access needs an explicit DNS allow rule. The HTTPS rule alone does not grant hostname-based access.

Upload The Policy

Write the singleton policy document:

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

Using source_groups[].mode: "audit" keeps the group active while converting deny outcomes for that group into allow.

Verify That The Policy Became Active

Check the stored policy document:

GET /api/v1/policy

Then check node readiness and runtime state:

GET /ready
GET /api/v1/stats

What you want to see:

  • the policy document exists
  • the node is ready
  • stats show the dataplane and policy state as healthy

Then inspect the DNS runtime specifically:

  • GET /api/v1/dns-cache
  • GET /api/v1/audit/findings

What you want to confirm:

  • queries for api.example.com are accepted and show up in DNS runtime state
  • traffic outside the declared policy shows up as audit findings instead of being silently allowed

Tighten The HTTPS Rule With TLS Metadata

Once the DNS-based flow looks correct, you can narrow the HTTPS rule further by requiring a specific SNI in TLS metadata mode:

{
  "id": "allow-api-example-https",
  "action": "allow",
  "match": {
    "proto": "tcp",
    "dst_ports": [443],
    "tls": {
      "mode": "metadata",
      "sni": {
        "exact": ["api.example.com"]
      }
    }
  }
}

Use this when SNI or certificate metadata is enough and you do not want active TLS interception. That gives you a good first-time progression:

  1. allow DNS for the hostname you intend
  2. allow HTTPS for the matching flow
  3. optionally require the expected TLS identity before you enforce broadly

Verify The Behavioral Result

Use a test host inside 10.10.0.0/16 and confirm:

  • DNS for api.example.com is allowed
  • HTTPS to api.example.com:443 is observed as allowed by the candidate policy
  • other unmatched traffic appears in audit findings

If the Neuwerk denies more than you expected, inspect:

  • GET /api/v1/audit/findings
  • GET /api/v1/dns-cache when hostname policy is involved
  • GET /api/v1/wiretap/stream when you need live confirmation

Promote The Policy To Enforce

When the audit evidence matches your intent, change the source-group mode to enforce and write the same policy again:

  • keep the same policy body
  • change only the source-group mode from audit to enforce

Warning

Changing a policy in enforce mode changes the active policy immediately. For larger rollouts, keep the source group narrow, validate DNS and audit behavior first, and only then broaden the source population.

Next Steps