Skip to content

simulate policy

Does the estate allow a flow end to end, and which rule decides it on each firewall?

Synopsis

proteus simulate policy <source> <destination> [flags]
proteus simulate policy <source> <destination> --file <config.xml> [flags]

The first form is path mode, the default. It traces the path as simulate routing does and checks the security policy of every firewall and vsys on that path. The second form checks one configuration file, with no inventory and no path.

Examples

A path that a firewall denies

$ proteus simulate policy 198.18.1.10 198.18.10.100 --port 443
denied at hop 2: fw01 / vsys1, rule block-servers (deny)

simulate policy 198.18.1.10 -> 198.18.10.100 tcp/443            fidelity: exact

  198.18.1.10
     │ 198.18.1.0/24
  ┌─ fw02 ─ vsys1 ─ router default ─ snapshot 1m ────────┐
  │  zones   home -> labor                               │
  │  in      vlan.1        198.18.1.1/24                 │
  │  out     vlan.32       198.19.0.1/24                 │
  │  route   198.18.0.0/15 via 198.19.0.254   static     │
  │  policy  interzone-default (allow)                   │
  └──┬───────────────────────────────────────────────────┘
     │ 198.19.0.0/24   198.19.0.1 -> 198.19.0.254
  ┌─ fw01 ─ vsys1 ─ router default ─ snapshot 1m ────────┐
  │  zones   transport -> server                         │
  │  in      ethernet1/1   198.19.0.254/24               │
  │  out     ethernet1/2   198.18.10.1/24                │
  │  route   198.18.10.0/24  connected                   │
  │  policy  block-servers (deny)                        │
  └──┬───────────────────────────────────────────────────┘
     │ 198.18.10.0/24
  198.18.10.100   delivered

firewalls on the path: fw02 (home -> labor), fw01 (transport -> server)

The first line gives the verdict. Each box is one hop, and its policy row names the rule that decides that hop. Path mode takes the zones from the path, so you give no zones.

A path that leaves the estate

$ proteus simulate policy 198.18.1.10 198.18.10.100 --port 443
undecided at hop 1: fw02 / vsys1, 198.19.0.77 leaves the estate (not in the inventory)

simulate policy 198.18.1.10 -> 198.18.10.100 tcp/443            fidelity: undermatch

  198.18.1.10
     │ 198.18.1.0/24
  ┌─ fw02 ─ vsys1 ─ router default ─ snapshot 1m ────────┐
  │  zones   home -> labor                               │
  │  in      vlan.1        198.18.1.1/24                 │
  │  out     vlan.32       198.19.0.1/24                 │
  │  route   198.18.0.0/15 via 198.19.0.77   static      │
  │  policy  interzone-default (allow)                   │
  └──┬───────────────────────────────────────────────────┘
     │ 198.19.0.0/24
  198.19.0.77   leaves the estate (not in the inventory)

firewalls on the path: fw02 (home -> labor)
may be incomplete: the path leaves the estate at 198.19.0.77
unresolved: fw02/vsys1: 198.19.0.77 leaves the estate (not in the inventory)

The next hop 198.19.0.77 is no firewall of the inventory, so Proteus cannot check the rest of the path. The run exits with code 3. See Undecided for every cause of an undecided hop.

One configuration with given zones

$ proteus simulate policy 10.2.0.5 10.1.0.5 --port 443 \
    --from-zone dmz --to-zone inside --file testdata/config/firewall-zones.xml
10.2.0.5 -> 10.1.0.5 tcp/443
file / vsys1   testdata/config/firewall-zones.xml
  zones      from dmz, to inside (given)
  relevance  unknown: no stored forwarding table
  fidelity   exact
first match: interzone-default (deny), default rule (built-in)
{
  "format": 2,
  "command": "simulate policy",
  "detail": "summary",
  "input": {
    "flow": {
      "source": {
        "addrs": [
          "10.2.0.5"
        ],
        "resolved": false
      },
      "destination": {
        "addrs": [
          "10.1.0.5"
        ],
        "resolved": false
      },
      "protocol": "tcp",
      "port": 443,
      "from_zone": "dmz",
      "to_zone": "inside"
    },
    "selection": {
      "file": "testdata/config/firewall-zones.xml"
    }
  },
  "results": [
    {
      "answer": "first match: interzone-default (deny), default rule (built-in)",
      "verdict": "stop",
      "reasons": [
        {
          "code": "verdict.default",
          "text": "default rule interzone-default (deny), built-in"
        }
      ],
      "rule": "interzone-default",
      "default_action": "deny",
      "fidelity": {
        "level": "exact"
      },
      "doubts": [],
      "zones": {
        "from": [
          "dmz"
        ],
        "to": [
          "inside"
        ],
        "source": "given"
      },
      "relevance": {
        "known": false,
        "relevant": false,
        "code": "gap.fib-missing",
        "text": "no stored forwarding table"
      },
      "target": {
        "device": "file",
        "vsys": "vsys1"
      }
    }
  ],
  "holes": [],
  "unresolved": [],
  "notes": []
}

No rule matches the flow from dmz to inside, so the built-in interzone-default rule denies it. The JSON tab shows the output of --output json --detail summary. The relevance is unknown, because a file holds no forwarding table.

An application on one configuration

$ proteus simulate policy 10.1.0.5 10.2.0.5 --application web-browsing --port 80 \
    --why --file demo/config.xml
10.1.0.5 -> 10.2.0.5 tcp/80
file / vsys1   demo/config.xml
  note: application data of content 8000-1000 from demo/apps.xml.gz
  note: the device can match the session again when App-ID identifies it later: an earlier application, such as ssl or web-browsing, can match another rule than web-browsing
  note: rule allow-remote matches web-browsing only through the implicit use of app-remote
  zones      from inside, to outside (configuration)
  relevance  unknown: no stored forwarding table
  fidelity   inferred
  resolve-source      exact    8 10.1.0.5: 0 hits, 0 negated rules
  resolve-destination exact    8 10.2.0.5: 0 hits, 0 negated rules
  derive-zones        inferred 8 from inside; to outside (configuration)
  match-application   exact    1 web-browsing: 0 explicit, 1 implicit, 0 kept in doubt (content 8000-1000)
  match-service       exact    1 tcp/80; protocol tcp, from the default of web-browsing (tcp/80; tcp/443/secure)
  match-url           exact    1 no candidate names a URL category
  drop-disabled       exact    1 0 disabled
  order               exact    1 1 in order
  first-match         exact    1 allow-remote (allow), position 8
  8. allow-remote allow [local vsys:vsys1]
first match: allow-remote (allow)

The App-ID data comes from apps.xml.gz beside the configuration. allow-remote names app-remote, whose implicit use holds web-browsing. The run gives no zones, so Proteus derives them and the answer is inferred.

Reading the output

Path mode

The first line is the verdict:

Line Meaning
allowed every hop passes and routing delivers the flow
denied at hop N: <device> / <vsys>, rule <name> (<action>) a rule or a default rule stops the flow
denied at hop N: no route to <address> on <device> routing drops the flow on that hop
undecided at hop N: <device> / <vsys>, <reason> Proteus cannot decide that hop

The first hop that stops the flow, or that is undecided, sets the verdict. Proteus still checks every other hop, and a hop after the deny shows (after the deny). A deny after an undecided hop leaves the verdict undecided, and a note names the later deny.

Each box holds the rows of simulate routing and a policy row with the hop's answer:

Row Meaning
policy <rule> (<action>) the rule that decides the hop
policy interzone-default (deny) no rule matches, and a default rule decides
policy undecided: <reason> the hop is undecided
policy not evaluated: <reason> the check did not run, for example after a routing drop
doubt <reason> a doubt that comes from the path or the zones, see Undecided

Each hop's check uses the hop's flow. That flow has the addresses after any NAT on an earlier hop, and the zones that routing gives on that hop.

The path starts where the source is connected, or where the most specific route to the source leaves. When two firewalls connect the source, or only default routes cover it, the command exits 2 and asks you to name the start with --device <name>.

Path mode needs one address per endpoint. Proteus resolves an FQDN endpoint with this machine's DNS and traces the first IPv4 address, and FQDN objects of that name still match. With --no-dns, or when the name has no IPv4 address, the command exits 2: "path mode needs an address for ; remove --no-dns or give an address".

Each device answers from its latest snapshot, or from its latest one at or before --at. For an HA pair, Proteus reads the snapshot of the active member.

--why adds the stages of routing, then one block per hop. The block holds the security verdict, the candidate rules with their doubts, the default rule and the stage table:

$ proteus simulate policy 198.18.1.10 198.18.10.100 --port 443 --why
denied at hop 1: fw02 / vsys1, rule interzone-default (deny)
...
hop 1: fw02 / vsys1, security stop: default rule interzone-default (deny), built-in
  - interzone-default deny [default built-in]
  resolve-source      exact 0 198.18.1.10: 2 hits, 0 negated rules
  resolve-destination exact 0 198.18.10.100: 1 hits, 0 negated rules
  derive-zones        exact 0 from home, to labor, as given
  match-application   exact 0 no application given
  match-service       exact 0 tcp/443
  match-url           exact 0 no candidate names a URL category
  drop-disabled       exact 0 0 disabled
  order               exact 0 0 in order
  first-match         exact 0 no enabled rule matches; default rule interzone-default (deny), built-in

--output json gives one result with these keys:

Key Content
mode the mode of the run
verdict allowed, denied or undecided
at the hop, the check, the rule and the reason that set the verdict
fidelity the fidelity of the answer
routing's fields the path, as simulate routing gives it
per hop: doubts, after_deny, checks.security the hop's doubts, whether it comes after the deny, and its security check

The checks.security block has the same keys as a --file result.

A destination that the firewall itself owns gets the same check as any other hop. A note says that Proteus does not check the firewall's own services, the interface management profile.

--file mode

The header shows the flow, then one block per vsys:

Row Meaning
file / <vsys> <path> the configuration and the vsys of the check
note: <text> a note, for example the App-ID data file that the run reads
zones the zones and where they come from: given or configuration
relevance always unknown: no stored forwarding table for a file
fidelity the fidelity of the answer, with the rules in doubt
unresolved: <vsys>: <reason> the rule that keeps the answer undecided

The last lines give the answer:

Line Meaning
first match: <rule> (<action>) the rule that decides the flow
first match: <rule> (<action>), default rule (<source>) no rule matches, and a default rule decides
first certain match: <rule> (<action>) the first rule that surely matches, in an undecided answer
undecided: <rule> (<action>) at position N may match first: <reason> the earlier rule in doubt that keeps the answer undecided

Without --from-zone and --to-zone, Proteus derives the zones from the interfaces and routes of the configuration. A derived zone is always inferred. --file does not check NAT, so a derived zone is the zone before NAT.

Warning

Derived zones can give a wrong answer. Against a lab firewall's own test security-policy-match, 3 of 7 probe flows agreed with derived zones and 7 of 7 with given zones. Give --from-zone and --to-zone when you know them.

With one derived zone on each side, the default rules decide a flow that no rule matches. With several derived zones on a side, or none, such a flow is undecided: "the default rule depends on the zones".

--why shows every stage, each candidate with its doubts, and the default rule:

$ proteus simulate policy 198.19.0.254 10.2.0.5 --port 443 --why \
    --from-zone labor --to-zone dmz --file testdata/config/firewall-doubt.xml
198.19.0.254 -> 10.2.0.5 tcp/443
file / vsys1   testdata/config/firewall-doubt.xml
  zones      from labor, to dmz (given)
  relevance  unknown: no stored forwarding table
  fidelity   overmatch: earlier candidates in doubt share the action deny: labor-app; not evaluated: application
  resolve-source      exact     14 198.19.0.254: 1 hits, 0 negated rules
  resolve-destination exact     12 10.2.0.5: 0 hits, 0 negated rules
  derive-zones        exact     1  from labor, to dmz, as given
  match-application   exact     1  no application given
  match-service       exact     1  tcp/443
  match-url           exact     1  no candidate names a URL category
  drop-disabled       exact     1  0 disabled
  order               exact     1  1 in order
  first-match         overmatch 1  every candidate is in doubt; default rule interzone-default (deny), built-in
  14. labor-app         deny [local vsys:vsys1]
      doubt: application not evaluated (dropbox)
  -   interzone-default deny [default built-in]
first match: interzone-default (deny), default rule (built-in)

labor-app names an application, and the run has no --application, so the rule is in doubt. It denies like the default rule, so the answer is still decided.

An undecided answer ends with the first rule that surely matches and the cause. That run exits with code 3:

$ proteus simulate policy 10.0.0.5 203.0.113.5 --port 443 \
    --from-zone dmz --to-zone wan --file testdata/config/firewall-doubt.xml
...
unresolved: file/vsys1: dmz-user (deny) at position 7 may match first: user not evaluated (corp\alice)

first certain match: dmz-plain (allow)
undecided: dmz-user (deny) at position 7 may match first: user not evaluated (corp\alice)

Stages

A check runs named stages. Each stage removes candidate rules and declares its fidelity. A --why row shows the stage, its fidelity, the candidates that remain, and the detail.

Stage What it does
resolve-source keeps rules whose source reaches the source address or FQDN
resolve-destination the same for the destination
derive-zones keeps rules whose zones and rule-type match, given or derived
match-application keeps rules whose application matches --application, explicit or through implicit use
match-service keeps rules whose service holds --port, or whose application-default holds it
match-url keeps rules whose URL category matches --url
drop-disabled removes disabled rules
order sorts the rest in evaluation order and lists the doubts of each rule
first-match decides at the first rule without doubt, else at a default rule

Undecided

Proteus decides a hop at the first candidate rule that it can evaluate in full. An earlier candidate that it cannot evaluate is in doubt, because the firewall can match it first. When every such rule has the same action, the hop is decided with the fidelity overmatch. When one of them has another action, the hop is undecided.

Cause Examples
a candidate above the match names an application an application or service application-default without --application or without App-ID data; an application that the App-ID data does not hold, see Applications
a candidate above the match names a service that Proteus cannot read a predefined service such as service-https that the snapshot does not hold, a service group that holds one, or no service
a candidate above the match names a value without data a user, a HIP profile or a schedule
a candidate above the match names a URL category without --url, or a category that the configuration does not define, such as a PAN-DB category
a candidate names a runtime source or destination an external dynamic list, a region or a dynamic address group; these rules stay candidates, because their members are known only at runtime
a doubt on the path ECMP (Proteus does not follow the other next hops), a PBF rule that can redirect the flow, a NAT or PBF answer that can miss matches, or a start that only a default route places
the zones the vsys of the hop is unknown, a zone is missing, a zone is the placeholder external of a vsys crossing, or the vsys does not define the zone
the default rules the local and the pushed override of a default rule have different actions, and Proteus does not know which one wins
the routing end the path leaves the estate, loops, or ends unresolved

When a PBF rule only may match, the hop also says why, for example a service and no --port.

Default rules and rule-type

A firewall evaluates its default rules after every other rule, and Proteus does the same. intrazone-default decides a flow with equal zones, and interzone-default decides a flow with different zones. The built-in actions are allow and deny, and an override in the configuration changes the action:

Source Where it comes from
built-in no override
local the default rule override of the vsys
pushed an override that Panorama pushed

When a local and a pushed override have the same action, the output shows local. When their actions differ, the hop is undecided.

Proteus applies the rule-type of each rule:

Rule-type Matches
universal both zones are in the lists of the rule
intrazone equal zones only
interzone different zones only

Path mode always knows both zones. With --file, rule-type and the default rules apply when you give both zones, or when Proteus derives one zone on each side. The answer is then inferred. With several derived zones on a side, or none, an intrazone or interzone rule stays in doubt (zone.derived). The answer is undecided when that rule can change it.

Applications

--application <name> gives the application of the flow: a predefined application or a custom application of the configuration. Proteus then matches it as the firewall does, from the App-ID data of the device.

Where the App-ID data comes from

Mode Source
path mode each hop reads the App-ID data of the content version of its snapshot; proteus fetch stores it, see App-ID data and fetch; the hops of one path can have different content versions
--file apps.xml.gz in the directory of the configuration; the note note.app-data-file names the file and its content version; nothing checks that the version is the device's; copy the file from <store>/.content/<version>.v1.xml.gz
no data a snapshot without a content version, a missing file or a file that Proteus cannot read gives the note note.app-data-missing; the answer is then the same as without --application

How a rule matches

The name takes any case. A custom application of that name wins over a predefined one. The answer writes the name as the data or the configuration writes it.

The match-application stage keeps three kinds of rule:

Kind A rule is one when
explicit its application is the flow's, any, a group that holds it at any depth, a filter that selects it, or a container that holds it
implicit it allows, and one of its predefined applications lists the flow's application in its implicit use
kept in doubt it names an application or a container that neither the data nor the configuration holds (doubt.application-unknown)

The first match comes in two passes. First come the explicit rules and the rules kept in doubt, in rule order. Then come the implicit rules, in rule order. So an explicit match wins over an implicit one, also when it comes later. The default rules come last.

A deny rule never matches through implicit use, and a custom application never implies another. An implicit match carries note.app-implicit, which names the application that implies the flow's application.

A filter counts the tags that the configuration adds to an application with application-tag. A filter exclude removes the named applications and every function of a named container.

Every answer with an application carries note.app-shift. The firewall can match the session again when App-ID identifies it later. Proteus evaluates one application per flow, as test security-policy-match does.

application-default

A rule with service application-default matches when the protocol and port of the flow are in the default ports of the application. For an implicit match, the ports are those of the rule's applications that imply the flow's application.

Default Matches
tcp/80,443, udp/53, ranges that protocol and those ports
a secure extended port, such as tcp/443/secure that port, with note.app-secure-port
tcp/dynamic, tcp/any any port of that protocol
an IP protocol, such as 89, or a range of them that protocol, any port
an ICMP or ICMPv6 type protocol 1 or 58, with note.app-icmp-type: Proteus does not check the type
no default any protocol and port

A rule with a custom service matches on the ports of the service. When such a port is not a default port of the application, note.app-non-default-port says so. Without --port, a rule with application-default stays in doubt (doubt.app-port-open).

The protocol

Without --protocol, --application takes the protocol of the application's default: ssl gives tcp, and ospf gives 89. An application with several default protocols, or with no default, leaves the protocol open. A rule that depends on the protocol then stays in doubt. The header line shows the protocol of the run.

simulate routing and simulate nat keep tcp. In path mode, routing and NAT see the open protocol, so a NAT or PBF rule that names a service stays in doubt. Give --protocol to decide it.

A protocol without ports, such as icmp or 89, never matches a custom service or a service group. Such a flow drops those rules, with or without --application.

A name that is no application

The firewall refuses an unknown name and a container as the application of a flow. With --file, Proteus exits 2 and suggests up to five names. For a container, the suggestions are its functions:

$ proteus simulate policy 10.1.0.5 10.2.0.5 --application office-suite --file demo/config.xml
proteus: --application office-suite is an application container in content 8000-1000, not an application; name one of its functions: office-docs, office-mail

In path mode, such a name leaves that hop undecided. The reason names the device and its content version, because another hop can have another content version.

Flags

Flag Default Description
--port <port> none destination port: 443 or tcp/443
--protocol <proto> tcp, or with --application the default of the application tcp, udp, sctp, icmp or a protocol number
--source-port <n> none source port
--from-zone <zone> derived with --file: the source zone; give both zones or neither
--to-zone <zone> derived with --file: the destination zone; give both zones or neither
--url <url> none URL, matched against custom URL categories
--application <name> none a predefined or custom application, matched with App-ID data, see Applications
--user <user> none source user; Proteus accepts the flag and does not evaluate it yet
--no-dns off do not resolve an FQDN endpoint
--router <name> none path mode with --device: start in this logical router
--each off check every selected firewall on its own; arrives in a later release
--why off show every stage: its fidelity, what it kept and why

The command takes the selection flags --device, --label, --vsys, --at and --file. In path mode, --device names the start firewall and --at picks the snapshot of each device. With --file, --vsys picks the vsys. For JSON and YAML, see --detail and results.

A zone that the vsys does not define exits 2, and the message lists the zones of the vsys. When you select several vsys, a vsys without the zone is a hole. The command then exits 2 only when no vsys defines the zone.

--url matches custom URL categories. A rule that names a PAN-DB category stays a candidate, in doubt. With --file, an FQDN endpoint resolves with this machine's DNS. The name matches FQDN objects, and the first address matches everything else. A note names the other addresses.

These flags exit 2 in path mode, and the message names the flag:

Flag Use instead
--vsys, --label, --from-zone, --to-zone the path gives the firewalls, the vsys and the zones; use --file <path> --vsys <name> for one configuration
--device a --device b path mode starts on one device
--router without --device add --device
--each arrives in a later release

With --file, --device, --label, --at and --router exit 2, because they select from the store. The command does not take --fresh, because path mode reads stored snapshots.

Exit codes

Code When
0 allowed or denied, with a complete answer
3 undecided, an unresolved entry, or a hole, such as a device without a snapshot or a configuration that Proteus cannot read
2 you must change the command line: no start, a start tie, or a flag that the mode refuses

The other codes are in Output and exit codes.

Limits

  • Proteus does not evaluate --user, so a rule that names a user is in doubt.
  • Without --application, or without App-ID data, a rule that names an application is in doubt.
  • Policy-based forwarding does not evaluate the application.
  • Proteus does not check the return path.
  • --file does not check NAT.

See Limits: simulate policy and Limits: applications.

See also