# panafapi.py

## command line interface to the AutoFocus API

# NAME

> panafapi.py - command line interface to the AutoFocus API

# SYNOPSIS

    panafapi.py [options]
       --sessions            search AutoFocus sessions
       -A                    get aggregate of sessions
       -H                    get histogram of sessions
       --session id          get AutoFocus session
       --samples             search AutoFocus samples
       --sample-analysis     get AutoFocus sample analysis report
       --top-tags            search AutoFocus top tags
       --tags                search AutoFocus tags
       --tag name            get AutoFocus tag
       --export              export AutoFocus list
       -r json               JSON API request (multiple -r's allowed)
       -n num                request num results
       --scope scope         search scope
       --hash hash           sample hash
       --terminal            get only final search result
       -t tag                .panrc tagname
       -K api_key            AutoFocus API key
       -V api_version        AutoFocus API version (default v1.0)
       -h hostname           AutoFocus hostname
       -p                    print response in Python to stdout
       -j                    print response in JSON to stdout
       -D                    enable debug (multiple up to -DDD)
       --ssl opt             SSL verify option: verify|noverify
       -T seconds            HTTP connect timeout
       --version             display version
       --help                display usage

# DESCRIPTION

> panafapi.py is used to perform AutoFocus API requests. It uses the PanAFapi class from the pan.afapi module to execute API requests.

> The options are:

> `--sessions`
>   Search AutoFocus sessions using the `/sessions/search/` and `/sessions/results/` API requests.
> `-A`
>   Search AutoFocus sessions using the `/sessions/aggregate/search/` and `/sessions/aggregate/results/` API requests.
> `-H`
>   Search AutoFocus sessions using the `/sessions/histogram/search/` and `/sessions/histogram/search/` API requests.
> `--session` id
>   Get details for AutoFocus session using the `/session/` API request.
> `--samples`
>   Search AutoFocus (WildFire) samples using the `/samples/search/` and `/samples/results/` API requests.
> `--sample-analysis`
>   Get details for a sample's WildFire analysis using the `/sample/{id}/analysis` API request.
> `--top-tags`
>   Search AutoFocus top tags data using the `/top-tags/search/` and `/top-tags/results/` API requests. This data corresponds to the Top Tags data in the AutoFocus portal dashboard and search statistics.
> `--tags`
>   Search AutoFocus tags using the `/tags/` API request.
> `--tag` name
>   Get details for an AutoFocus tag using the `/tag/` API request.
> `--export`
>   Export a list of saved AutoFocus artifacts using the `/export/` API request.
> `-r` json

>   JSON object to use in the body of the API request.

>   Multiple `-r` options are allowed.

>   json can be a JSON string, a path to a file containing JSON, or the value - to specify that JSON is on stdin.

> `-n` num

>   Specify number of results for the request.

>   This is a convenience option and sets the `pageSize` string for `--tags` and the `size` string for the search options to num in the JSON body of the request.

> `--scope` scope

>   Specify the scope for the request.

>   This is a convenience option and sets the `scope` string for `--tags` and the search options to scope in the JSON body of the request.

> `--hash` hash

>   Specify the hash for the request.

>   This sets the `sampleid` argument for the `--sample-analysis` (PanAFapi `sample_analysis()` method) request. The `sampleid` is the SHA256 hash of the sample.

> `--terminal`

>   Set the `terminal` argument for the `*_search_results()` PanAFapi methods to `True`.

>   This specifies that only the terminal (complete) search result should be returned.

>   By default intermediate (incomplete) search results are returned (the `terminal` argument is set to `False`).

> `-t` tag
>   Specify tagname for .panrc file.
> `-K` api_key
>   Specify the API key for the request.
> `-V` api_version

>   Specify the API version for the request.

>   API version is a string in the form vmajor.minor or major.minor (e.g., v1.0). The API version is used to determine the PanAFapi class implementation to use.

>   The default API version can be determined by running `panafapi.py -D`.

> `-h` hostname

>   URI hostname used in API requests. This can also be specified in a .panrc file using the `hostname` varname.

>   The default is `autofocus.paloaltonetworks.com`.

> `-p`
>   Print JSON response in Python to stdout.
> `-j`
>   Print JSON response to stdout.
> `-D`
>   Enable debugging. May be specified multiple times up to 3 to increase debugging output.
> `--ssl` opt

>   Specify the type of SSL server certificate verification to be performed.

>   `verify`
>     Perform SSL server certificate verification. This is the default.
>   `noverify`
>     Disable SSL server certificate verification.
> `-T` seconds
>   The HTTP connect `timeout` in seconds.
> `--version`
>   Display version.
> `--help`
>   Display command options.

> The following describes the options used to perform each AutoFocus API request:

> Options | PanAFapi Method | API Resource URIs
> --- | --- | ---
> --sessions | sessions_search_results() | /sessions/search/ /sessions/results/
> --sessions -A | sessions_aggregate_search_results() | /sessions/aggregate/search/ /sessions/aggregate/results/
> --sessions -H | sessions_histogram_search_results() | /sessions/histogram/search/ /sessions/histogram/results/
> --session id | session() | /session/
> --samples | samples_search_results() | /samples/search/ /samples/results/
> --sample-analysis | sample_analysis() | /sample/{id}/analysis
> --top-tags | top_tags_search_results() | /top-tags/search/ /top-tags/results/
> --tags | tags() | /tags/
> --tag name | tag() | /tag/
> --export | export() | /export/

# FILES

> `.panrc`
>   .panrc file.

# EXIT STATUS

> panafapi.py exits with 0 on success and 1 if an error occurs.

# EXAMPLES

> Note

> Examples may use the jp.py program from JMESPath.

> Add AutoFocus API key with tagname autofocus to .panrc file.

> First Get Your API Key.

>     $ KEY=e3222942-2080-11e7-b1c7-03f23b1b6cb4
>     $ echo "api_key%autofocus=$KEY" >>.panrc

> Verify API key.

>     $ panafapi.py -t autofocus --tags
>     tags: 200 OK tags=50 total_count=1394

> Get 10 tags using `-n 10`.

>     $ panafapi.py -t autofocus --tags -j -n 10 | jp.py 'tags[].public_tag_name'
>     tags: 200 OK tags=10 total_count=1394
>     [
>         "Commodity.180Solutions",
>         "Commodity.1stBrowser",
>         "Commodity.360Root",
>         "Unit42.4H",
>         "Unit42.777Ransomware",
>         "Commodity.7ev3n",
>         "Unit42.7ev3nHONEST",
>         "Unit42.7h9rRansomware",
>         "Unit42.9002",
>         "Unit42.AbaddonPOS"
>     ]

> Get tag details.

>     $ panafapi.py -t autofocus --tag Unit42.777Ransomware -j | jp.py tag
>     tag: 200 OK
>     {
>         "count": 9,
>         "lasthit": "2016-05-28 05:50:27",
>         "tag_class": "malware_family",
>         "description": "777 ransomware appears to have been around since September 2015,but several new samples were discovered during mid-2016. This ransomware will encrypt files and append the .777 extension to them. There is a public decryptor that will automatically decrypt any files that end with the .777 extension.",
>         "tag_definition_status_id": 1,
>         "up_votes": 1,
>         "created_at": "2017-02-14 10:59:23",
>         "tag_class_id": 3,
>         "tag_definition_scope_id": 4,
>         "tag_definition_scope": "unit42",
>         "comments": [],
>         "updated_at": "2017-02-14 10:59:23",
>         "tag_definition_status": "enabled",
>         "source": "Unit 42",
>         "tag_name": "777Ransomware",
>         "public_tag_name": "Unit42.777Ransomware",
>         "refs": "[{\"source\":\"BleepingComputer\",\"title\":\"Emsisoft Releases Decryptors for the Xorist and 777 Ransomware\",\"url\":\"https://www.bleepingcomputer.com/news/security/emsisoft-releases-decryptors-for-the-xorist-and-777-ransomware/\",\"created\":\"2017-01-30T12:50:49\"}]",
>         "customer_name": "Palo Alto Networks Unit42"
>     }

> Search private samples for malware and save results.

>     $ cat q-malware.json
>     {
>         "query": {
>             "children": [
>                 {
>                     "field": "sample.malware",
>                     "operator": "is",
>                     "value": 1
>                 }
>             ],
>             "operator": "all"
>         }
>     }

>     $ panafapi.py -t autofocus --samples -r q-malware.json --scope private -n 100 -j > malware-private.json
>     samples_search: 200 OK 339 0%
>     samples_results: 200 OK 556 0% hits=0 total=0 time=0:00:00.591
>     samples_results: 200 OK 10% hits=8 total=8 time=0:00:03.636
>     samples_results: 200 OK 18% hits=9 total=9 time=0:00:04.658
>     samples_results: 200 OK 35% hits=29 total=29 time=0:00:07.145
>     samples_results: 200 OK 41% hits=74 total=74 time=0:00:07.966
>     samples_results: 200 OK 73% hits=89 total=89 time=0:00:10.715
>     samples_results: 200 OK 93% hits=91 total=91 time=0:00:11.592
>     samples_results: 200 OK 100% hits=94 total=94 time=0:00:12.566 "complete"

> Display some results.

>     $ jp.py -f malware-private.json 'hits[0:2]._source.[create_date,filetype,tag]'
>     [
>         [
>             "2017-03-30T13:14:29",
>             "PE",
>             [
>                 "Commodity.WildFireTest"
>             ]
>         ],
>         [
>             "2017-03-30T12:24:30",
>             "PE",
>             [
>                 "Commodity.WildFireTest"
>             ]
>         ]
>     ]

> Get sample analaysis details.

>     $ jp.py -f malware-private.json 'hits[0]._source.[sha256]'
>     [
>         "3886f96be7f889f38b88e93b12188eed6974ace9223334e7c0aa366a3cb61200"
>     ]

>     $ HASH=3886f96be7f889f38b88e93b12188eed6974ace9223334e7c0aa366a3cb61200

>     $ panafapi.py -t autofocus --sample-analysis --hash $HASH -j > $HASH.json
>     sample-analysis: 200 OK

> Display report connection section.

>     $ jp.py -f $HASH.json 'connection'
>     {
>         "win7": [
>             {
>                 "line": "unknown , udp , 23.96.94.144:123 , US",
>                 "b": 32901349,
>                 "m": 6590112,
>                 "g": 359377
>             },
>             {
>                 "line": "unknown , udp , 224.0.0.252:5355 , -",
>                 "b": 20249526,
>                 "m": 7999437,
>                 "g": 371806
>             }
>         ],
>         "winxp": [
>             {
>                 "line": "unknown , udp , 23.96.94.144:123 , US",
>                 "b": 32901349,
>                 "m": 6590112,
>                 "g": 359377
>             }
>         ]
>     }

# SEE ALSO

> pan.afapi

> AutoFocus API Reference Guide
>   https://docs.paloaltonetworks.com/autofocus/autofocus-api.html
> View API Request for a Search as panafapi.py command line
>   https://docs.paloaltonetworks.com/autofocus/autofocus-whats-new/autofocus-release-history/new-features-march-2016/api-request-for-a-search.html
> AutoFocus Administrator's Guide
>   https://docs.paloaltonetworks.com/autofocus/autofocus-admin.html

# AUTHORS

> Palo Alto Networks, Inc. <techbizdev@paloaltonetworks.com>