panwfapi.py

command line program for accessing the WildFire API

NAME

panwfapi.py - command line program for accessing the WildFire API

SYNOPSIS

panwfapi.py [options]
   --submit path|url     submit file or URL to WildFire for analysis
   --report              get WildFire report
   --verdict             get WildFire sample verdict
   --sample              get WildFire sample file
   --pcap                get WildFire PCAP files
   --changed             get changed verdicts
   --hash hash           query MD5 or SHA256 hash
   --platform id         platform ID for sandbox environment
   --testfile            get sample malware test file
   --format format       report output format
   --date date           start date for changed verdicts (YYYY-MM-DD)
   --dst dst             save file to directory or path
   -K api_key            WildFire API key
   -h hostname           WildFire hostname
   -x                    print XML response to stdout
   -p                    print XML response in Python to stdout
   -j                    print XML response in JSON to stdout
   -D                    enable debug (multiple up to -DDD)
   -t tag                .panrc tagname
   -T seconds            urlopen() timeout
   --http                use http URL scheme (default https)
   --nocacloud           disable default cloud CA certificate verification
   --cafile path         file containing CA certificates
   --capath path         directory of hashed certificate files
   --version             display version
   --help                display usage

DESCRIPTION

panwfapi.py is used to perform API requests on the WildFire cloud. It uses the PanWFapi class from the pan.wfapi module to execute API requests.

The options are:

--submit path|url
Submit a file or URL to WildFire for analysis. Valid URL schemes for url are: file, http, https and ftp. A file url is the same as specifying path.
--report
Get analysis report for a previously uploaded sample. The sample can be specified by its MD5 or SHA256 hash (--hash).
--verdict
Get the verdict(s) for previously uploaded samples. The samples can be specified by their MD5 or SHA256 hash (--hash).
--sample
Get a previously uploaded sample file. The sample can be specified by its MD5 or SHA256 hash (--hash).
--pcap
Get PCAP (packet capture) file of network activity for a previously uploaded sample. The sample can be specified by its MD5 or SHA256 hash (--hash). The sandbox environment for the PCAP can optionally be specified using the platform ID (--platform). If no platform is specified a PCAP from an environment that resulted in a Malware verdict is returned.
--changed
Get the hashes of samples whose verdicts have changed within the last 30 days starting at the date specified with --date.
--hash hash
MD5 or SHA256 hash for a WildFire sample. --hash can be specified multiple times for queries which allow multiple hashes. It can also be a path to a file containing the hashes or '-' to specify that hashes be read from stdin.
--platform id

Platform ID for sandbox environment. Valid platform IDs are:

Platform ID Sandbox Environment
1 Windows XP, Adobe Reader 9.3.3, Office 2003
2 Windows XP, Adobe Reader 9.4.0, Flash 10, Office 2007
3 Windows XP, Adobe Reader 11, Flash 11, Office 2010
4 Windows 7, Adobe Reader 11, Flash 11, Office 2010
5 Windows 7 x64 SP1, Adobe Reader 11, Flash 11, Office 2010
201 Android 2.3, API 10, avd2.3.1
--testfile

Get sample malware test file. Each request returns a similar PE (Portable Executable) file named wildfire-test-pe-file.exe with a different hash and with verdict Malware.

This currently requires an api_key even though it is not needed for the API request.

--format format

WildFire report output format string. This can be xml or pdf.

The default is xml.

--date date

Start date for --changed query. The format for the date argument is YYYY-MM-DD.
--dst dst

Save file to the directory or path specified in dst. By default files are saved with the filename specified in the HTTP response attachment. Files saved are:

  • WildFire samples (--sample)

    sha256-hash-of-sample

  • PDF files (--format=pdf)

    sha256-hash-of-sample.pdf

  • PCAP files (--pcap)

    sha256-hash-of-sample.platform.unknown.pcap

  • Malware test file (--testfile)

    wildfire-test-pe-file.exe

-K api_key
Specify the api_key used in API requests. This can also be specified in a .panrc file using the api_key varname.
-h hostname

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

This is used to test alternate clouds (e.g., beta.wildfire.paloaltonetworks.com).

The default is wildfire.paloaltonetworks.com.

-x
Print XML response to stdout.
-p
Print XML response in Python to stdout.
-j
Print XML response in JSON to stdout.
-D
Enable debugging. May be specified multiple times up to 3 to increase debugging output.
-t tag
Specify tagname for .panrc.
-T seconds
Specify the timeout value for urlopen().
--http
Use http URL scheme for API requests. This can be used with the --testfile option to get a malware test file over HTTP.
--nocacloud

Disable default cloud CA SSL server certificate verification.

By default SSL server certificate verification is performed using the Go Daddy Class 2 Certification Authority Root Certificate which is used by the WildFire cloud and is stored in the PanWFapi class. --nocacloud can be used to disable verification for test clouds or if the cloud CA changes.

urlopen() only supports SSL server certificate verification in Python version 3.2 and greater.

--cafile path
Specify the cafile value for urlopen(). cafile is a file containing CA certificates to be used for SSL server certificate verification. --cafile disables default cloud certificate verification. --cafile is only supported in Python version 3.2 and greater.
--capath path
Specify the capath value for urlopen(). capath is a directory of hashed certificate files to be used for SSL server certificate verification. --capath disables default cloud certificate verification. --capath is only supported in Python version 3.2 and greater.
--version
Display version.
--help
Display command options.

FILES

.panrc
.panrc file. See PanXapi documentation for .panrc format.

EXIT STATUS

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

EXAMPLES

Add WildFire API key to .panrc file.

$ echo 'api_key%wildfire=d3b07384d113edec49eaa6238ad5ff00' >>.panrc

Submit file to WildFire for analysis and print XML response.

$ panwfapi.py -t wildfire -x --submit /tmp/sample.exe
submit: 200 OK [response_body=True response_type=xml]

<?xml version="1.0" encoding="UTF-8" ?><wildfire><upload-file-info><url></url><filename>sample.exe</filename><sha256>5a036546422c5235283254234fc5a67a36e3221a2324a3087db0081f08cc38e6</sha256><md5>ada8501b1e2abae90a83cc4cf20196d8</md5><size>466356</size><filetype>PE32 executable</filetype></upload-file-info></wildfire>

Query WildFire sample report by MD5 hash and print XML response.

$ panwfapi.py -t wildfire -x --report --hash 6de476723a12ad277a84f031868aace3 | head
report: 200 OK [response_body=True response_type=xml]
<?xml version="1.0" encoding="UTF-8" ?>
<wildfire>
<version>2.0</version>
<file_info>
    <sha256>74e330f15ac544a7e5201b9bed97d4425058a47bd10a6763932181f78b99116e</sha256>
    <md5>6de476723a12ad277a84f031868aace3</md5>
    <filetype>PE</filetype>
    <size>313856</size>
    <malware>yes</malware>
</file_info>

Get previously uploaded sample.

$ panwfapi.py -t wildfire --sample --hash 6de476723a12ad277a84f031868aace3 --dst /tmp
sample: 200 OK [attachment="74e330f15ac544a7e5201b9bed97d4425058a47bd10a6763932181f78b99116e"]
saved /tmp/74e330f15ac544a7e5201b9bed97d4425058a47bd10a6763932181f78b99116e

Get PCAP file of sample network activity.

$ panwfapi.py -t wildfire --pcap --hash 11727b1d9ed03799a756d1bbb84e6319 --platform 4
pcap: 200 OK [attachment="033e2d2ea39ffd9285d75edff1171c4b9f28fb407a314010f87f5d7ed98517d6.4.1.pcap"]
saved 033e2d2ea39ffd9285d75edff1171c4b9f28fb407a314010f87f5d7ed98517d6.4.1.pcap

Submit URL to WildFire for analysis and print XML response in JSON.

$ panwfapi.py -t wildfire -j --submit \
> https://www.paloaltonetworks.com/content/dam/paloaltonetworks-com/en_US/assets/pdf/datasheets/wildfire/wildfire.pdf
submit: 200 OK [response_body=True response_type=xml]
{
  "wildfire": {
    "upload-file-info": {
      "filename": null,
      "filetype": "Adobe PDF document",
      "md5": "b81a9805d672bc6d574bd76ffd09ad54",
      "sha256": "716bc87686b4242c4e446fdb4599cf112fdd6fd85600a30a1856a67cc61b9c25",
      "size": "1236454",
      "url": "https://www.paloaltonetworks.com/content/dam/paloaltonetworks-com/en_US/assets/pdf/datasheets/wildfire/wildfire.pdf"
    }
  }
}

Get malware test file over HTTP.

$ panwfapi.py --testfile --http -K 0
testfile: 200 OK [attachment="wildfire-test-pe-file.exe"]
saved wildfire-test-pe-file.exe

SEE ALSO

pan.xapi

WildFire Administrator's Guide
https://www.paloaltonetworks.com/documentation/61/wildfire/wf_admin.pdf.html
WildFire API
https://www.paloaltonetworks.com/documentation/61/wildfire/wf_admin/wildfire-api.html

AUTHORS

Kevin Steves <kevin.steves@pobox.com>