Manage the host firewall

By the end of this tutorial you'll know your machine's current firewall posture, how to get the suggested command to open or close a port, and why this is a different layer of protection from the domain allowlist. SSG does not change firewall state itself: ssg firewall reports status and prints suggested commands that you run yourself.

Hand this to your AI agent

Show me the current firewall posture on this machine. Do not run any
firewall-changing command: enable, disable, allow, deny and delete only
print a suggested host command, and I run that command myself.

1. Run `ssg firewall status --json` and summarize: which backend was
   detected, whether the firewall is enabled, and anything else the
   summary field says (including whether root/administrator privilege is
   needed to see the live rule list).
2. If I ask you to open a specific port, run
   `ssg firewall allow --port=<N> --proto=tcp` to print the suggested host
   command, show it to me and wait for me to say "yes, run it" before you
   run the host command.
3. Never run a host firewall command (ufw, nft, pfctl, netsh) without me
   having seen and approved the exact command first.

What your agent will do

• Report your current firewall posture with one read-only command.
• Print the suggested host command for anything you ask it to change, without running it.
• Never run the suggested host command without your explicit go-ahead. The ssg firewall verbs themselves do not change the firewall.

What you do yourself: decide what should be open, and type "yes, run it" (or run the suggested command in the dashboard's governed terminal, where you can watch it execute).

Step by step

1. Check the current status

ssg firewall status

{
  "Backend": "ufw",
  "Enabled": false,
  "Summary": "read from /etc/ufw/ufw.conf (non-root fallback — `ufw status verbose` requires root and no passwordless sudo is configured for this binary): ENABLED=no. Run `sudo ssg firewall status` for the full live rule summary.",
  "FallbackSource": "ufw.conf"
}

Without root, SSG reports what it can determine from config files and tells you exactly what to run for the full live picture. This is intentional — SSG never fabricates a status it can't actually verify.

2. Understand the CLI's scope

The ssg firewall command does not apply host firewall rules. status reads the state of the local firewall backend (ufw preferred, nftables fallback on Linux). The verbs enable, disable, allow, deny and delete only print a suggested command for this OS and exit. They never run ufw, nftables, pfctl or netsh:

ssg firewall allow  --port=8080 --proto=tcp                    # prints the suggested command to open a port; changes nothing
ssg firewall deny   --port=22   --proto=tcp --from=10.0.0.0/24
ssg firewall delete --port=8080 --proto=tcp
ssg firewall enable
ssg firewall disable

Run the printed command yourself, in the governed terminal or in your own shell. Add --json to get the suggested command as JSON ("applied": false).

Flags: --port (1–65535, required for allow/deny/delete), --proto (tcp or udp, default tcp), --from (optional source CIDR, e.g. 10.0.0.0/24), --comment (optional, A-Za-z0-9 _.-, max 64 chars). The --yes flag is still accepted for older scripts, but nothing requires it. This command requires an active license the same way ssg eval/ssg check/ssg serve do. This page does not claim an audit record for these commands.

3. Changing the firewall needs root

The suggested host command needs the privilege the backend needs: root on Linux with ufw or nftables. You run that command yourself, usually with sudo. Reading the full live status also needs root:

sudo ssg firewall status

4. Manage it from the dashboard instead

The dashboard's Firewall page (/firewall) is a posture panel modeled on tools like Little Snitch/TinyFirewall: it always shows a determinable state — ready, needs-privilege, no-backend, unsupported-os, or error — never a bare "daemon unreachable" unless the API call itself genuinely failed. The page also offers premade command cards (status, enable, a suggested allow and a suggested deny). The cards give you the host command to run yourself in the governed terminal, so you watch the real command execute rather than trusting a button. SSG does not apply the change for you. Disabling the firewall or adding a deny rule can sever remote admin access, so read the command before you run it.

5. What this looks like per OS

OS	Backend	What you can do
Linux	ufw (preferred) or nftables (fallback)	Status, plus suggested commands for allow/deny/delete/enable/disable. You run the suggested command yourself, with root.
macOS	Application Firewall (socketfilterfw) for the global switch, pfctl for typed rules	The dashboard's posture probe reports what's detected and what privilege is required. The CLI prints suggested commands for this OS. Check ssg firewall --help on that machine for the current scope.
Windows	netsh advfirewall	Same posture-probe pattern. SSG never changes the firewall itself; a suggested mutating command needs an elevated (Administrator) terminal when you run it.

If you're unsure what your specific install supports, ssg firewall status and ssg firewall --help on that machine are the source of truth — always check there before assuming parity across your fleet.

6. How this relates to the domain allowlist

The firewall and the domain allowlist operate at different layers:

• Host firewall (this page) — L3/L4, whole-machine, port- and CIDR-based. It doesn't know or care which process or AI agent is making a connection.
• SSG domain allowlist / Egress Guard — application layer, per-tool-call or per-request, domain- and URL-based, agent-aware, with an audit trail of exactly which agent requested what.

Use the firewall for coarse host-level exposure control (what's reachable from the network at all) and the allowlist for fine-grained control over what your AI agent specifically is permitted to reach.

Verify

ssg firewall status --json

Confirm Backend matches what you expect for this OS and Enabled reflects reality. If you just ran a suggested command, re-run status (or sudo ssg firewall status for the live rule list) and confirm the rule is present rather than assuming it worked.

If something goes wrong

Symptom	Cause	Next step
Status shows a fallback summary instead of live rules	Not running as root/Administrator	Re-run with sudo (Linux) or from an elevated terminal (Windows)
ssg firewall allow or enable printed a command but the firewall did not change	ssg firewall only prints the suggested command	Run the printed host command yourself, with the privilege it needs
Dashboard shows needs-privilege	The daemon process itself isn't running with the privilege the backend requires	Run the suggested command in the governed terminal and elevate (sudo) there, rather than restarting the whole daemon as root
Dashboard shows no-backend	Neither ufw nor nftables (Linux) — or the equivalent backend on your OS — could be found	Install the backend your OS uses, then re-check status
A rule you added with the suggested allow command doesn't seem to work	The backend may need to be enabled first to enforce anything	Check ssg firewall status for Enabled: true before assuming a specific rule is the problem

Next

• Allow the network domains your agent may reach — the application-layer complement to this host-level control.
• Use the governed terminal — where you run the suggested firewall commands.
• Security & Trust — the broader threat model this fits into.