panwfapi.py - command line program for accessing the WildFire API
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
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.
- .panrc
- .panrc file. See PanXapi documentation for .panrc format.
panwfapi.py exits with 0 on success and 1 if an error occurs.
Add WildFire API key to .panrc file.
$ echo 'api_key%wildfire=d3b07384d113edec49eaa6238ad5ff00' >>.panrcSubmit 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/74e330f15ac544a7e5201b9bed97d4425058a47bd10a6763932181f78b99116eGet 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.pcapSubmit 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
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
Kevin Steves <kevin.steves@pobox.com>