Skip to content

search

Where does an address, prefix, port, URL, user or name appear in your configurations?

Synopsis

proteus search <term> [selection flags] [flags]

Examples

Search for an address

$ proteus search 10.124.0.1 --file testdata/config/firewall-multivsys.xml
search 10.124.0.1 (covers)

file / vsys1   testdata/config/firewall-multivsys.xml
  object    address       corp-dc-vienna       10.124.0.1/32
  object    address       corp-location-vienna 10.124.0.0/16
  group     address-group corp-dc              holds corp-dc-vienna
  group     address-group corp-location        holds corp-location-vienna
  reference security rule Corp DC Access       destination -> corp-dc
  reference security rule Corp DC Access       source -> corp-location
1 with results, 2 without, 0 holes
{
  "format": 2,
  "command": "search",
  "detail": "full",
  "input": {
    "direct": false,
    "fields": null,
    "kinds": null,
    "limit": 0,
    "mode": "covers",
    "selection": {
      "file": "testdata/config/firewall-multivsys.xml"
    },
    "show": null,
    "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"
    },
    {
      "answer": "file/vsys1: address-group corp-dc",
      "device": "file",
      "vsys": "vsys1",
      "stage": "group",
      "kind": "address-group",
      "name": "corp-dc",
      "via": "holds corp-dc-vienna",
      "scope": "shared"
    },
    {
      "answer": "file/vsys1: address-group corp-location",
      "device": "file",
      "vsys": "vsys1",
      "stage": "group",
      "kind": "address-group",
      "name": "corp-location",
      "via": "holds corp-location-vienna",
      "scope": "shared"
    },
    {
      "answer": "file/vsys1: security rule Corp DC Access (destination)",
      "device": "file",
      "vsys": "vsys1",
      "stage": "reference",
      "kind": "security rule",
      "name": "Corp DC Access",
      "field": "destination",
      "via": "corp-dc",
      "path": "/config/devices/localhost.localdomain/vsys/vsys1/rulebase/security/rules/Corp DC Access",
      "scope": "vsys:vsys1"
    },
    {
      "answer": "file/vsys1: security rule Corp DC Access (source)",
      "device": "file",
      "vsys": "vsys1",
      "stage": "reference",
      "kind": "security rule",
      "name": "Corp DC Access",
      "field": "source",
      "via": "corp-location",
      "path": "/config/devices/localhost.localdomain/vsys/vsys1/rulebase/security/rules/Corp DC Access",
      "scope": "vsys:vsys1"
    }
  ],
  "summary": {
    "answer": "1 with results, 2 without, 0 holes",
    "found": 6,
    "with": 1,
    "without": 2,
    "omitted": 0
  },
  "holes": [],
  "unresolved": [],
  "notes": []
}

The address lies in two objects: a host and the /16 network that covers it. Each object reaches the rule Corp DC Access through a group. The other two vsys of the file hold no finding.

Find the group to edit

$ proteus search 10.1.1.1 --file testdata/config/firewall-nested-groups.xml
search 10.1.1.1 (covers)

file / vsys1   testdata/config/firewall-nested-groups.xml
  object    address       h-1         10.1.1.1/32
  group     address-group g-inner     holds h-1
  group     address-group g-middle    holds h-1
  group     address-group g-outer     holds h-1
  reference address-group g-inner     static -> h-1
  reference address-group g-middle    static -> g-inner
  reference address-group g-outer     static -> g-middle
  reference security rule allow-outer source -> g-outer
1 with results, 0 without, 0 holes

The rule names only g-outer, and the address sits three groups down. Add --direct to keep the groups one level up, and --show to drop the references:

$ proteus search 10.1.1.1 --direct --show objects,groups \
    --file testdata/config/firewall-nested-groups.xml
search 10.1.1.1 (covers)

file / vsys1   testdata/config/firewall-nested-groups.xml
  object address       h-1     10.1.1.1/32
  group  address-group g-inner holds h-1
1 with results, 0 without, 0 holes

Find addresses written into rules

$ proteus search 198.18.1.1 --file testdata/config/firewall-literals.xml
search 198.18.1.1 (covers)

file / vsys1   testdata/config/firewall-literals.xml
  object    address       named-host   198.18.1.1/32
  reference security rule named-rule   source -> named-host
  literal   security rule literal-host source 198.18.1.1/32
  literal   security rule literal-net  source 198.18.0.0/16
1 with results, 0 without, 0 holes

Some configurations write addresses into rule fields and name no object. The literal stage finds these rules, here a host and a /16 that covers the term.

Search for an application

$ proteus search ssl --file demo/config.xml
search ssl (matches)

file / vsys1   demo/config.xml
  note: application data of content 8000-1000 from demo/apps.xml.gz
  object    application       ssl          predefined
  group     application-group inner        holds inner > ssl
  group     application-group outer        holds outer > inner > ssl
  reference application-group inner        members -> ssl
  reference application-group outer        members -> inner
  reference security rule     allow-outer  application -> outer
  reference security rule     allow-remote application -> implicit use by app-remote
1 with results, 0 without, 0 holes

With the device's App-ID data, search finds each place that selects the application. The rule allow-remote allows ssl only through the implicit use of app-remote. The data comes from the snapshot, or with --file from apps.xml.gz beside the configuration (see Simulate policy).

Reading the output

The first line repeats the term and the match in parentheses. Each block is one device and one vsys. The summary line counts the vsys with results, the vsys without results, and the holes.

Stages

Each row starts with its stage. The stages print in this order:

Stage What it finds
object objects whose value holds the term, and objects with that name
group groups that hold one of those objects, at any depth
reference rules, NAT rules, groups and profiles that name one of them
literal rules that write the term directly into a field

A rule whose field is any reaches every value, but no object leads to it. Search leaves such rules out (see Concepts).

Terms

The term's type sets the default match (see Concepts).

Term Match in the first line What search finds
address, such as 10.124.0.1 covers objects and literals whose value holds the address
prefix or range, such as 10.124.0.0/24 overlaps objects and literals whose value overlaps it
port, such as tcp/8006 or 8006 covers every service whose range holds the port, such as tcp/8000-8100
URL, such as shop.example.com/cart matches values that match by PAN-OS URL tokens
user, such as ACME\carol matches the user groups that hold the user, with a user snapshot
anything else matches objects with that exact name or value
any term with --within, --exact or --contains within, exact or contains see Flags

A configuration does not say which directory groups a user belongs to. Set PROTEUS_USERS to a user snapshot to search for a user:

PROTEUS_USERS=testdata/users-snapshot.json \
  proteus search 'ACME\carol' --file testdata/config/firewall-users.xml

URL categories in security profiles

A URL category can reach a rule through the rule's security profile, besides the rule's category field. The reference then shows the profile path:

  reference security rule       via-group          profile-setting -> default > default-url-filter alert demo-category
  reference security rule       via-named-profile  profile-setting -> default-url-filter alert demo-category
  reference url-filtering       default-url-filter alert -> demo-category

A profile inspects traffic that a rule already matched. The rule does not match because of the profile.

Applications

Finding What it says
object application the application; predefined marks an application of the App-ID data
object application-filter a filter that selects it, with the fields that select it, such as category=media, risk=4
object application-container the container that holds it
group application-group a group that holds it, with the path through nested groups: outer > inner > ssl
reference security rule a rule that names it, or a group, filter or container that holds it
... implicit use by <app> an allow rule that allows it only through the implicit use of another application

The term takes any case, and the findings use the name as the data writes it. A filter exclude that names the application, or its container, shows as a reference.

Without App-ID data, search finds only the custom applications of the configuration. The note note.app-data-missing then says what search cannot find: filters, containers and implicit use.

Flags

Search takes the selection flags --device, --label, --vsys, --at, --fresh and --file (see Selection flags).

Flag Default Description
--within off keeps values that lie wholly inside the term (addresses, prefixes, ranges)
--exact off keeps values equal to the term
--contains off keeps names and values that hold the term as text
--kind <kinds> every kind keeps objects and groups of these kinds, such as address,service
--field <fields> every field keeps references and literals from these fields, such as source,destination
--show <stages> every stage keeps these stages: objects, groups, refs, literals
--direct off keeps only the groups one level up from an object
--why off adds each finding's answer line under its row
--limit N every finding keeps the first N findings (see Results)
--detail full with --output json or yaml, see Detail

You can use only one of --within, --exact and --contains at a time.

--within and --exact compare an address's whole value, in an object or written into a rule. The range 10.0.0.2-10.0.0.9 is not within 10.0.0.0/29, because two of its addresses lie outside it. It is also not exactly 10.0.0.4/30.

--contains compares text and ignores the term's type. Use it to find a long URL in a custom URL category, because a category name cannot hold the URL.

--limit N counts findings in the usual order, over all devices and vsys together. It takes 1 or more, and --limit 0 is a usage error with exit 2. The counts on the summary line stay for the whole answer, and the line ends with 2 of 6 shown, narrow by device, vsys or kind. In JSON and YAML, summary.found counts every finding and summary.omitted counts the findings that the limit leaves out. The limit never cuts holes, unresolved entries or notes. In text, the notes of a vsys whose findings the limit leaves out print below the findings, as note: fw02/vsys1: <text>.

Limits

  • A search for a prefix or range, or with --within or --exact, lists each wildcard address object that can hold one of its addresses as unresolved, and exits with code 3.
  • A reference outside any vsys, such as a static route, matches by name alone, with scope config.
  • Without App-ID data, search finds no filter, container or implicit use of an application.

See Limits.

See also