pan.wfapi - Python interface to the WildFire API
import pan.wfapi
try:
wfapi = pan.wfapi.PanWFapi(tag='wildfire')
except pan.wfapi.PanWFapiError as msg:
print('pan.wfapi.PanWFapi:', msg, file=sys.stderr)
sys.exit(1)
sample = '/var/wildfire/samples/sample1.exe'
try:
wfapi.submit(file=sample)
except pan.wfapi.PanWFapiError as msg:
print('submit:', msg, file=sys.stderr)
sys.exit(1)
print('sample %s submitted' % sample)
print(wfapi.response_body)
The pan.wfapi module defines the PanWFapi class, which provides an interface to the WildFire API.
PanWFapi provides an interface to all WildFire API requests:
Request URI path submit file /publicapi/submit/file submit URL /publicapi/submit/url get previously uploaded sample /publicapi/get/sample get sample PCAP /publicapi/get/pcap get sample analysis report /publicapi/get/report get sample verdict /publicapi/get/verdict get sample verdicts /publicapi/get/verdicts get verdicts changed /publicapi/get/verdicts/changed get sample malware test file /publicapi/test/pe
- __version__
- pan package version string.
- DEBUG1, DEBUG2, DEBUG3
- Python logging module debug levels (see Debugging and Logging below).
- BENIGN, MALWARE, GRAYWARE, PENDING, ERROR, UNKNOWN, INVALID
- Constants for the integer verdict values.
- VERDICTS
- A dictionary which maps the integer verdict values to a tuple of (name, description).
class pan.wfapi.PanWFapi(tag=None, hostname=None, api_key=None, timeout=None, http=False, cacloud=True, cafile=None, capath=None)
- tag
- .panrc tagname.
- hostname
URI 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.
- api_key
- api_key argument used in API requests. This can also be specified in a .panrc file using the api_key varname.
- timeout
- The timeout value for urlopen() in seconds.
- http
- Use http URL scheme for API requests. This can be used with the testfile() method to get a malware test file over HTTP.
- cacloud
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. cacloud=False 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
- The cafile value for urlopen(). cafile is a file containing CA certificates to be used for SSL server certificate verification. By default the SSL server certificate is not verified. cafile is only supported in Python version 3.2 and greater.
- capath
- The capath value for urlopen(). capath is a directory of hashed certificate files to be used for SSL server certificate verification. By default the SSL server certificate is not verified. capath is only supported in Python version 3.2 and greater.
Exception raised by the PanWFapi class when an error occurs. The string representation of an instance of this exception will contain a user-friendly error message.
The submit() method submits a file or URL to WildFire for analysis.
The sample() method gets a previously uploaded sample file. The sample can be specified by its MD5 or SHA256 hash.
The report() method gets an analysis report for a previously uploaded sample. The sample can be specified by its MD5 or SHA256 hash. The report format can be xml or pdf. The default is xml.
The verdict() and verdicts() methods get the verdict(s) for previously uploaded samples. The sample can be specified by its MD5 or SHA256 hash. The verdict() hash argument is a single hash and the verdicts() hashes argument is a list of up to 500 hashes.
The result is an XML document with verdict represented as an integer:
Value Verdict Description 0 benign 1 malware 2 grayware -100 pending sample exists and verdict not known -101 error sample is in error state -102 unknown sample does not exist -103 invalid hash is invalid (verdicts() method only)
The verdicts_changed() method gets the hashes of samples whose verdicts have changed within the last 30 days starting at the date specified. The format for the date argument is YYYY-MM-DD.
The pcap() method gets a PCAP (packet capture) file of network activity for a previously uploaded sample. The sample can be specified by its MD5 or SHA256 hash. The sandbox environment for the PCAP can optionally be specified using the platform ID. If no platform is specified a PCAP from an environment that resulted in a Malware verdict is returned.
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
The testfile() method gets a 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.
The attachment data attribute is a dictionary used to access a downloaded file's filename and content; it will contain two keys:
Key Value filename filename field in content-disposition header content file content from HTTP message body
The http_code data attribute contains the HTTP response status code.
Status codes that can be returned include:
HTTP status-code, reason-phrase Description 401 Unauthorized API key invalid 403 Forbidden Permission denied 404 Not Found Report/sample/pcap not found 405 Method Not Allowed Must use method POST 413 Request Entity Too Large Sample size exceeds maximum 418 Invalid file type 419 Quota Exceeded Maximum daily uploads exceeded 419 Quota Exceeded Maximum daily queries exceeded 420 Insufficient Arguments Missing required request parameter 421 Invalid Argument Invalid request parameter 422 URL Download Error URL download error 456 Invalid request 513 File upload failed
The http_reason data attribute contains the HTTP response reason phrase.
The response_body data attribute contains the HTTP response message body.
The response_type data attribute is set to xml when the message body is an XML document.
The Python standard library logging module is used to log debug output; by default no debug output is logged.
In order to obtain debug output the logging module must be configured: the logging level must be set to one of DEBUG1, DEBUG2, or DEBUG3 and a handler must be configured. DEBUG1 enables basic debugging output and DEBUG2 and DEBUG3 specify increasing levels of debug output.
For example, to configure debug output to stderr:
import logging if options['debug']: logger = logging.getLogger() if options['debug'] == 3: logger.setLevel(pan.wfapi.DEBUG3) elif options['debug'] == 2: logger.setLevel(pan.wfapi.DEBUG2) elif options['debug'] == 1: logger.setLevel(pan.wfapi.DEBUG1) handler = logging.StreamHandler() logger.addHandler(handler)
- .panrc
- .panrc file
The panwfapi.py command line program calls each available PanWFapi method and can be reviewed for sample usage.
panwfapi.py
- 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>