Skip to main content

Manage the host firewall

By the end of this tutorial you'll know your machine's current firewall posture, how to open or close a port through SSG, and why this is a different layer of protection from the domain allowlist.

Hand this to your AI agent​

Show me the current firewall posture on this machine. Do not enable,
disable, allow, or deny anything — those are destructive and need my
explicit confirmation, and the enable/disable/deny/delete verbs all
require --yes anyway.

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, show me the exact command you
   would run (`ssg firewall allow --port=<N> --proto=tcp`) and wait for me
   to say "yes, run it" before executing.
3. Never construct a `--yes`-flagged command yourself without me having
   seen and approved the exact flags first.

What your agent will do​

  • Report your current firewall posture with one read-only command.
  • Draft the exact command for anything you ask it to change, without running it.
  • Never touch enable, disable, deny, or delete without your explicit go-ahead — these are destructive and gated by --yes in the CLI itself.

What you do yourself: decide what should be open, and type "yes, run it" (or approve it in the dashboard, which routes the same command through the governed terminal so 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 manages the local Linux firewall backend (ufw preferred, nftables fallback). All destructive changes — enable, disable, deny, delete — require an explicit --yes flag:

ssg firewall allow  --port=8080 --proto=tcp                    # opens a port — never requires --yes, fully audited
ssg firewall deny   --port=22   --proto=tcp --from=10.0.0.0/24 --yes
ssg firewall delete --port=8080 --proto=tcp --yes
ssg firewall enable  --yes                                     # switches to default-deny
ssg firewall disable --yes

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). This command requires an active license the same way ssg eval/ssg check/ssg serve do.

3. Managing rules generally needs root​

Actually changing firewall state (as opposed to reading the config-file fallback) requires the privilege the backend needs — root on Linux via ufw/nftables. Run with sudo when a command reports it needs elevation:

sudo ssg firewall allow --port=8080 --proto=tcp

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. If your host needs elevated privilege to act, Enable and Disable don't try to silently self-elevate. Instead they run the equivalent ssg firewall enable|disable --yes (with sudo prefixed if needed) inside the governed terminal and take you straight to that session (/terminal?session=<id>), so you watch the real command execute rather than trusting a button. Disabling the firewall or adding a deny rule shows a confirmation dialog first, since either can sever remote admin access.

5. What this looks like per OS​

OSBackendWhat you can do
Linuxufw (preferred) or nftables (fallback)Full status + rule management (allow/deny/delete/enable/disable) via the CLI or the dashboard's governed-terminal flow. Requires root for changes.
macOSApplication Firewall (socketfilterfw) for the global switch, pfctl for typed rulesThe dashboard's posture probe reports what's detected and what privilege is required. Full management support depends on your installed ssg build — check ssg firewall --help on that machine, since the command's own help text documents Linux support explicitly.
Windowsnetsh advfirewallSame posture-probe pattern; mutating actions need an elevated (Administrator) terminal — SSG never attempts to self-elevate, it refuses and tells you to re-run from an elevated session.

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 added a rule, re-run status (or sudo ssg firewall status for the live rule list) and confirm it's present rather than assuming the write succeeded.

If something goes wrong​

SymptomCauseNext step
Status shows a fallback summary instead of live rulesNot running as root/AdministratorRe-run with sudo (Linux) or from an elevated terminal (Windows); the dashboard's Enable/Disable buttons route through the governed terminal specifically to make this path usable without you manually finding a privileged shell
enable/disable/deny/delete refuses without --yesThese are destructive by designAdd --yes once you're certain — there's no separate confirmation step for the CLI path
Dashboard shows needs-privilegeThe daemon process itself isn't running with the privilege the backend requiresClick Enable/Disable anyway — it opens the governed terminal where you can sudo/elevate directly, rather than needing to restart the whole daemon as root
Dashboard shows no-backendNeither ufw nor nftables (Linux) — or the equivalent backend on your OS — could be foundInstall the backend your OS uses, then re-check status
A rule you added with ssg firewall allow doesn't seem to workThe allow command itself is fully audited and doesn't need --yes, but the underlying backend may need enable --yes first to actually be enforcing anythingCheck ssg firewall status for Enabled: true before assuming a specific rule is the problem

Next​