Skip to content

Architecture

Proteus is one Go module with a read-only core, a set of question packages, and front ends for the command line and MCP. ARCHITECTURE.md in the repository root gives the reasoning behind each decision, and AGENTS.md lists the rules that every package follows.

Design goals

Goal What it means
Read-only The API client sends only <show> commands and the configuration export.
Correct before complete An answer that may be incomplete says so. A wrong answer that looks complete is the worst outcome.
Schema first Field knowledge comes from the PAN-OS schema.
Scope-correct Every answer is keyed by device and vsys. See Scope.

Layers

flowchart TB
    FE["front ends<br/>cli · mcp"]
    QUERY["query<br/>one typed answer per question"]
    subgraph Q["Questions"]
        SEARCH["search"]
        CARD["card<br/>(lookup)"]
        DRIFT["drift<br/>(diff)"]
        SIM["simulate<br/>policy · nat · routing"]
    end
    ESTATE["estate<br/>devices + time → targets"]
    subgraph IO["Device and disk"]
        INV["inventory"]
        FETCH["fetch<br/>read-only XML API"]
        STORE["store<br/>snapshots"]
    end
    subgraph CORE["Read-only core (no I/O)"]
        INDEX["index<br/>scope-keyed indexes"]
        RESOLVE["resolve<br/>PAN-OS semantics"]
        CONFIG["config<br/>load + schema digest"]
    end
    FE --> QUERY
    FE --> FETCH
    QUERY --> Q
    QUERY --> ESTATE
    ESTATE --> STORE
    FETCH --> INV
    Q --> INDEX
    INDEX --> RESOLVE --> CONFIG

Dependencies point down. The core imports no network or process package, and internal/archtest fails the build when an import breaks this rule.

Packages

Package Job
cmd/proteus the main package: signal handling and version, then cli.Run
internal/cli the commands, their text output and the settings
internal/mcp the MCP server: tools, schemas, audit and call limits
internal/query answers each question with a typed envelope, for both front ends
internal/config loads a configuration into an element tree and attaches the schema digest
internal/resolve PAN-OS semantics: vsys targets, rule order, object visibility, groups, tag filters, URL patterns, zones, routes
internal/index scope-keyed indexes: references, group closure, address containment, rule bitmaps
internal/search the four search stages for one scope
internal/card the whole rule or object behind a name
internal/drift changes between two configurations of a scope
internal/simulate the staged simulation framework and fidelity
internal/simulate/securitypolicy security rule matching
internal/simulate/nat NAT rule matching and translation
internal/simulate/routing paths across firewalls
internal/simulate/pathpolicy the security verdict of a flow along its path
internal/simulate/topology interfaces and forwarding tables, shared by the simulations
internal/simulate/rulebase rulebase address matching and the PBF check
internal/appid the App-ID content file of one content version
internal/estate turns a selection and a time into the configurations a question reads
internal/inventory the device list, credentials and TLS choice
internal/fetch the read-only XML API client and the list of documents
internal/store timestamped snapshots on disk, latest and retention
internal/task runs an operation as named steps and records each one
internal/reason the registry of reason codes that answers carry
internal/runlog one log file per run, with secret redaction
internal/schema parses the PAN-OS schema grammar
internal/digest the compact schema digest format
internal/tools/schemadigest developer tool: turns a firewall's schema.xml into a digest

Data flow of a question

sequenceDiagram
    participant U as user
    participant C as cli
    participant E as estate
    participant S as store
    participant X as config / index
    participant Q as search or simulate
    U->>C: proteus search 10.1.1.5
    C->>E: selection + time
    E->>S: latest snapshot per device
    S-->>E: config.xml, fib.xml, ...
    E->>X: load once per device, index per vsys
    E-->>C: targets (device, vsys)
    C->>Q: run per target
    Q-->>C: findings, holes, unresolved
    C-->>U: text or JSON, exit code

A device that Proteus cannot read becomes a hole, and the question runs on the other devices.

The schema digest

Every firewall carries its configuration schema at /opt/pancfg/mgmt/factory/schema.xml. The schema gives:

  • the fields, with their types, limits and defaults
  • whether a list holds named entries or plain members
  • the objects that a field can reference (memberof)

internal/tools/schemadigest turns the schema into a compact gzipped digest. The digest is committed in internal/config/schemadigest/ and embedded in the binary. config reads every configuration with this one digest and does not check the PAN-OS version.

resolve and index read the configuration as an element tree, guided by the digest. A newer schema therefore needs a new digest and no code change.

Simulation framework

A simulation is a sequence of named stages over one flow and one device. Each stage narrows a candidate set and declares its fidelity, and the framework computes the answer's fidelity from the stages.

internal/simulate knows no simulation kind. Each kind lives in its own package and plugs its stages into the framework.

Rules

AGENTS.md lists the rules, and each rule names the test that enforces it. The main ones:

Rule Summary
R1 Field knowledge comes from the schema only.
R2 Read-only everywhere.
R3 Nothing is dropped silently.
R5, R10 Resolution and indexes are keyed by scope.
R9 Every claim about PAN-OS behavior cites its source.
R12 Imports point one way; the core has no I/O.