Skip to content

Configuration

Proteus reads its settings from the inventory file, environment variables and flags, and writes its data to fixed paths.

The inventory

The inventory is a YAML file that lists your firewalls and the default settings. proteus inventory init writes a template.

Item Value
Default path ~/.config/proteus/config.yaml, or $XDG_CONFIG_HOME/proteus/config.yaml
Other path --config <path> or PROTEUS_CONFIG
Mode 0600. Proteus refuses to read the file when other users can read it.
version: 1

defaults:
  insecure_tls: true             # see "TLS" below
  timeout: 60                    # seconds per API call
  snapshot_keep: 20              # snapshots kept per device, with and without a configuration
  username: admin                # the login used to get an API key
  password_env: PANOS_PASSWORD   # the variable that holds the password
  max_snapshot_age: 24h          # answers from older snapshots carry a note
  output: text                   # text, json or yaml
  log_level: info                # error, warn, info or debug
  log_keep: 20                   # run logs kept
  # log_dir: ~/.local/state/proteus/log
  # store: ~/.local/share/proteus
  # export_inventory: true       # see "The inventory export" below

devices:
  - name: fw01
    host: fw01.example.net
    labels:
      site: vienna
    # ha_peer: fw01-b.example.net

snapshot_keep counts two groups separately. A fetch keeps the newest N snapshots that hold a configuration and the newest N that hold none, such as failed exports. A fetch never removes the snapshot that latest names.

Device fields

Field Meaning
name The name you select the device by. Letters, digits, ., _ and -.
host The management address or host name.
labels Free key/value pairs, selected with --label key=value.
username, password_env Override the defaults for this device.
insecure_tls, timeout Override the defaults for this device.
ha_peer The reachable host of the HA peer, when the address that the device reports is unreachable.

Passwords

Put the password in an environment variable and name the variable in password_env. A literal password: field also works, but it keeps the password on disk.

TLS

The template turns certificate verification off

insecure_tls: true turns off TLS certificate verification, because lab firewalls present self-signed certificates. Anyone on the network path can then read the password during login and send false data, and every answer from false data is false.

Set insecure_tls: false for each firewall whose certificate this machine trusts. You can set it per device.

Settings

Each setting comes from, in rising precedence: the built-in default, the inventory's defaults:, an environment variable, and a flag.

Setting Inventory key Variable Flag Default
inventory file PROTEUS_CONFIG --config ~/.config/proteus/config.yaml
snapshot store store PROTEUS_STORE --store ~/.local/share/proteus
snapshot age limit max_snapshot_age PROTEUS_MAX_SNAPSHOT_AGE --max-age 24h
output format output PROTEUS_OUTPUT --output text
color color PROTEUS_COLOR --color auto
log level log_level PROTEUS_LOG_LEVEL --log-level info
log directory log_dir PROTEUS_LOG_DIR --log-dir ~/.local/state/proteus/log
logs kept log_keep 20
inventory export export_inventory false
user snapshot PROTEUS_USERS none

The XDG_CONFIG_HOME, XDG_DATA_HOME and XDG_STATE_HOME variables move the default paths.

The user snapshot

A configuration holds no mapping from users to directory groups. PROTEUS_USERS points to a JSON file with that mapping:

{
  "taken_at": "2026-09-28T08:00:00Z",
  "groups": {
    "ACME\\carol": ["engineering"],
    "ACME\\alice": ["engineering", "finance"]
  }
}

taken_at is required, and an answer that uses an old user snapshot carries a note. Each command reads the file when it runs. proteus mcp reads it once at start and stops with exit 2 when it cannot, so a changed file needs a server restart.

The inventory export

proteus mcp reads its device list from an export of the inventory in the store. Set export_inventory: true under defaults:, and every fetch run writes <store>/.proteus/inventory.yaml, also when the run fails.

Property Value
Content the inventory without username, password and password_env, in the defaults and on every device
Write a temporary file, renamed into place, mode 0600
Export fails, snapshots stored exit 3 with note.export-failed
Nothing stored exit 1

The server refuses an export that holds a credential. It ignores the exported store and log_dir and uses its own. .proteus cannot clash with a device name, because a device name starts with a letter or a digit.

The mcp section

The mcp: section configures proteus mcp. Write it in the inventory, and the export carries it to the server. Each key is optional. The values below are the defaults, except for token_file, allowed_hosts and audit_log, which have none.

mcp:
  listen: 127.0.0.1:8765                 # host:port for --http
  token_file: /run/secrets/proteus-mcp-token
  allowed_hosts: [proteus.example.org]   # optional: Host header values --http accepts
  identity_header: X-User-Claims         # the header with the caller's claims
  audit_claims: [sub]                    # the claims each audit line records
  audit_log: /var/log/proteus/mcp-audit.jsonl   # or - for standard output (--http only)
  audit_max_mb: 100                      # the audit file's size before it rotates
  audit_keep: 10                         # rotated audit files kept
  log_dir: ~/.local/state/proteus/log/mcp  # run logs of the calls
  log_keep: 200
  max_concurrent: 4                      # calls answered at once
  max_queue: 16                          # calls waiting for a slot
  max_wait: 10s
  call_timeout: 60s
  max_loads: 2                           # snapshot loads at once
  max_cache: 2048                        # MB

Proteus refuses an unknown key, a negative number, a duration it cannot read, a listen without a port, an identity_header that is not an HTTP header name, and an empty audit_claims entry. A number that is left out or set to 0 takes its default, so max_queue: 0 keeps the queue at 16.

Each mcp setting comes from, in rising precedence: its default, the export's mcp: section, a variable, and a flag. The server reads no other file.

Key Variable Flag
listen PROTEUS_MCP_LISTEN --listen
token_file PROTEUS_MCP_TOKEN_FILE --token-file
allowed_hosts PROTEUS_MCP_ALLOWED_HOSTS (comma-separated) --allowed-host (repeatable)
identity_header PROTEUS_MCP_IDENTITY_HEADER
audit_claims PROTEUS_MCP_AUDIT_CLAIMS (comma-separated)
audit_log PROTEUS_MCP_AUDIT_LOG --audit-log
audit_max_mb PROTEUS_MCP_AUDIT_MAX_MB --audit-max-mb
audit_keep PROTEUS_MCP_AUDIT_KEEP --audit-keep
log_dir PROTEUS_MCP_LOG_DIR
log_keep PROTEUS_MCP_LOG_KEEP
max_concurrent PROTEUS_MCP_MAX_CONCURRENT --max-concurrent
max_queue PROTEUS_MCP_MAX_QUEUE --max-queue
max_wait PROTEUS_MCP_MAX_WAIT --max-wait
call_timeout PROTEUS_MCP_CALL_TIMEOUT --call-timeout
max_loads PROTEUS_MCP_MAX_LOADS --max-loads
max_cache PROTEUS_MCP_MAX_CACHE --max-cache

The token

The inventory never holds the token: token_file names the file that holds it.

Source Precedence
--token-file highest
PROTEUS_MCP_TOKEN, the token itself middle
PROTEUS_MCP_TOKEN_FILE, or token_file from the export lowest

Proteus has no --token flag, because the process list shows every flag. It trims trailing whitespace from the token and refuses a token file that other users can write. A read-only secret mount (mode 0444, owned by root) is accepted. --http needs a token of at least 32 bytes.

Host check

allowed_hosts is optional. When you set it, --http answers only a request whose Host is in the list and gives 403 to every other request. When you leave it out, the server accepts every Host, and its start line says Host check off.

The token alone keeps out a request that DNS rebinding sends, so the Host check is defense in depth. Set it when the proxy forwards a fixed host name. Write each entry as a host name or address with no port and no brackets: the server removes the port from the request's Host before it compares.

Audit

--http needs audit_log. Over stdio, the server writes an audit file only when audit_log is set.

Transport Identity in the audit line
stdio the operating system user (auth: stdio, identity_source: os)
HTTP, header present the audit_claims of identity_header (auth: token, identity_source: header)
HTTP, header missing or not a JSON object unknown (identity_source: none)
HTTP, JSON object with none of the audit_claims unknown (identity_source: header)

Before a line takes the audit file past audit_max_mb, Proteus renames the file to <audit_log>.<UTC time>-<sequence> and starts a new one with mode 0600. It keeps the audit_keep renamed files with the highest sequence numbers and removes the older ones. Proteus also sets an existing audit file to mode 0600.

audit_log: - writes the lines to standard output, for a container platform that collects them. With --http, nothing else goes to standard output. Over stdio, standard output carries MCP, so the server refuses - with exit 2. The MCP guide lists the fields of an audit line.

Run logs of calls

log_dir defaults to mcp under the CLI's log directory (--log-dir, PROTEUS_LOG_DIR). Keep it a separate directory: each directory keeps only its newest logs, so call logs in the CLI's directory push out the CLI's logs.

The server writes a call's run log only when the call ends internal or timeout. At --log-level debug it writes one for every call. --max-age, --log-level and --store apply to the server too, and max_snapshot_age comes from the export's defaults:.

Files Proteus writes

Path Mode Content
~/.config/proteus/config.yaml 0600 the inventory, written once by inventory init
~/.local/share/proteus/<device>/<time>/ 0700 / 0600 one snapshot
<store>/.content/ 0700 / 0600 one App-ID content file per content version, <version>.v<trim>.xml.gz
~/.local/state/proteus/log/ 0700 / 0600 one log file per run, <command>-<time>-<seq>.log
<store>/.proteus/inventory.yaml 0700 / 0600 the inventory export, with export_inventory: true
~/.local/state/proteus/log/mcp/ 0700 / 0600 one log file per MCP call, mcp-<tool>-<time>-<seq>.log
audit_log 0600 the MCP audit, one JSON line per call, appended