Output and exit codes¶
Proteus prints text for people, and JSON or YAML for scripts. The exit code tells a script whether the answer is complete.
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | A complete answer. An empty answer is complete. |
| 1 | An error stopped the command, and no answer exists. |
| 2 | A usage error: a bad flag, a missing argument, or a name with several kinds. Change the command line. |
| 3 | An answer with holes or unresolved entries. The output is valid, but it can miss matches. |
| 130 | Interrupted by SIGINT (Ctrl-C). |
| 143 | Interrupted by SIGTERM. |
fetch uses the codes differently:
| Code | fetch result |
|---|---|
| 0 | every device stored every document |
| 3 | a device or a document failed, and at least one device stored |
| 1 | no device stored |
fetch prints its answer in all three cases.
Fail a pipeline on an incomplete answer¶
proteus simulate policy 10.20.1.5 10.1.250.10 --port 443 --output json > answer.json
case $? in
0) echo "complete" ;;
3) echo "incomplete or undecided: check holes and unresolved"; exit 1 ;;
*) echo "error"; exit 1 ;;
esac
The envelope¶
--output json and --output yaml print one envelope per command. Both formats
have the same keys, the same values and the same shape.
| Key | Holds |
|---|---|
format |
the envelope version, 2 |
command |
the command name, for example search |
detail |
full or summary |
input |
the typed input: term, selection and flags |
results |
the answer; always an array, empty when there is nothing to show |
summary |
counts and the count line, for search, lookup and snapshot diff |
holes |
devices or vsys that the command could not read |
unresolved |
entries that the command could not evaluate |
notes |
facts that qualify the answer and leave it unchanged |
holes, unresolved and notes are at the top level, so a script cannot miss
them. format changes only when a field changes its meaning or is removed.
$ proteus search 10.124.0.1 --vsys vsys1 --show objects --output json \
--file testdata/config/firewall-multivsys.xml
{
"format": 2,
"command": "search",
"detail": "full",
"input": {
"direct": false,
"fields": null,
"kinds": null,
"limit": 0,
"mode": "covers",
"selection": {
"file": "testdata/config/firewall-multivsys.xml",
"vsys": [
"vsys1"
]
},
"show": [
"objects"
],
"term": "10.124.0.1"
},
"results": [
{
"answer": "file/vsys1: address corp-dc-vienna",
"device": "file",
"vsys": "vsys1",
"stage": "object",
"kind": "address",
"name": "corp-dc-vienna",
"via": "10.124.0.1/32",
"scope": "vsys:vsys1"
},
{
"answer": "file/vsys1: address corp-location-vienna",
"device": "file",
"vsys": "vsys1",
"stage": "object",
"kind": "address",
"name": "corp-location-vienna",
"via": "10.124.0.0/16",
"scope": "vsys:vsys1"
}
],
"summary": {
"answer": "1 with results, 0 without, 0 holes",
"found": 2,
"with": 1,
"without": 0,
"omitted": 0
},
"holes": [],
"unresolved": [],
"notes": []
}
Results¶
Each result of simulate, search, lookup and snapshot diff has an answer:
the line of the text output that says what the result found, for example
denied at hop 2: fw01 / vsys1, rule block-servers (deny). The summary of
search, lookup and snapshot diff has the counts, with the count line as its
answer.
--limit N keeps the first N results, and summary.omitted counts the results
that it left out. For snapshot diff, N counts single changes: results holds
the scopes up to the scope where the limit falls.
Detail¶
The questions take --detail full (the default) or --detail summary.
| Detail | Each result keeps |
|---|---|
full |
everything: candidates, stage tables, each hop's interfaces and lookups |
summary |
the answer, the verdict, the fidelity, the reasons and the needs; of a path, each hop's device, vsys, snapshot, zones, route and policy verdict |
Holes, unresolved entries and notes stay in both.
Needs¶
A simulate result that is undecided, or whose fidelity is undermatch, has a
needs list. It names the inputs that can change the answer when you give them
in a second question.
| Code | Input |
|---|---|
input.port |
--port |
input.protocol |
--protocol |
input.url |
--url |
input.application |
--application, when the device has App-ID data |
input.from-zone, input.to-zone |
--from-zone, --to-zone, for --file with derived zones |
Each entry has the code, the input name, and a text that names the rules
the input decides.
- The list stops at the first rule in doubt that no input can settle, such as a rule that names only a user. Past that rule, no input changes the verdict.
- A rule in doubt for a port and for a user still lists the port, because the port can rule it out.
- An empty list means that no input can help.
- A decided result has a
needskey only when its fidelity isundermatch. simulate natwithout a protocol listsinput.protocolbesideinput.port. With a port and no protocol, it listsinput.protocolfor each NAT rule whose service holds that port.
Reason codes¶
Every hole, unresolved entry and note is an object with a code and a text,
beside device and vsys. Lists of reasons, such as fidelity.reasons, hold
{"code", "text"} objects too. Match the code in a script. The text is for
people and can change.
"unresolved": [
{
"device": "file",
"vsys": "vsys1",
"code": "doubt.not-evaluated.user",
"text": "dmz-user (deny) at position 7 may match first: user not evaluated (corp\\alice)"
}
]
A code reads <class>.<name>. The class is one of doubt, gap, path, zone,
default, dns, input, note, call and verdict. Every code comes from the
closed registry in internal/reason/registry.go, where each entry has a one-line
description.
A reason built from several parts lists each part with its own code. The text output can join consecutive unresolved entries of one composite on one line, and JSON lists them separately.
JSON schemas¶
schemas/out/ holds the JSON schema of each envelope, one file per command and
detail: simulate-policy.full.json, search.summary.json and so on.
simulate-policy-file.* is simulate policy --file. Every JSON example in the
tests validates against these schemas.
Errors in JSON and YAML mode¶
On a non-zero exit, the last line of stderr is one JSON object:
{"format":2,"exit":3,"log":"/home/u/.local/state/proteus/log/search-….log"}
{"format":2,"exit":2,"error":"unknown flag: --bogus"}
| Key | Present |
|---|---|
error |
on every exit except 3; on exit 3 the answer on stdout says what is missing |
log |
when a run log opened |
Earlier stderr lines, such as the --verbose echo, can come before this line.
Run logs¶
Every command writes one log file in the log directory. A command that fails or
exits with code 3 prints the path of its log. --log-level debug records every
API call and, for a simulation, what each stage kept. Proteus redacts passwords
and API keys from every log.