: Search Samples and Sessions
Focus
Focus

Search Samples and Sessions

Table of Contents

Search Samples and Sessions

Use the
/samples/search
and
/sessions/search
resources to search through samples and sessions, respectively. The sample search mimics the search functionality available through the AutoFocus web portal and provides corresponding data, such as WildFire™ verdict, SHA1 hash, file size, and file type. The session search also corresponds to information available through the
Sessions
tab when you perform a search in the AutoFocus web portal.

Resources

/samples/search/ /sessions/search/ /stix/samples/search/ /stix/sessions/search/

JSON Sample

View the corresponding cURLrequestor Python syntax for initiating searches for samples, sessions, and aggregate data from the AutoFocus web portal.

Request

The following request body searches for malware that originates from Algeria. It restricts the results to 50 private samples (samples within an organization) and sorts them in descending order based on when the sample was last updated.
curl -X POST https://autofocus.paloaltonetworks.com/api/v1.0/samples/search/ -H "Content-Type: application/json" -d '{ "apiKey":"apikey", "query":{ "operator":"all", "children":[ { "field":"session.src_country", "operator":"is", "value":"Algeria" } ] }, "size":50, "from":0, "sort":{ "update_date":{ "order":"desc" } }, "scope":"private" }'

Response

Use the
af_cookie
parameter to view the results of your search.
{ "af_in_progress": true, "af_first_result_af_took": 0, "in_progress": true, "af_cookie": "0-39173c38-b7bd-4c4b-93ec-6e403a35d0ac+0", "af_complete_percentage": 0, "bucket_info": { "minute_points": 200, "daily_points": 25000, "minute_points_remaining": 190, "daily_points_remaining": 24936, "minute_bucket_start": "2015-10-21 15:48:14", "daily_bucket_start": "2015-10-21 14:41:07" } }

STIX Sample

Request

The following request body searches for malware that originates from Algeria. It restricts the results to 50 private samples (samples within an organization) and sorts them in descending order based on when the sample was last updated.
curl -X POST https://autofocus.paloaltonetworks.com/api/v1.0/stix/samples/search -H "Content-Type: application/xml" -d ' <req> <apiKey>apikey</apiKey> <query> <operator>all</operator> <children> <item> <field>session.src_country</field> <operator>is</operator> <value>Algeria</value> </item> </children> </query> <size>50</size> <from>0</from> <sort> <update_date> <order>desc</order> </update_date> </sort> <scope>private</scope> </req>'

Response

Use the
af_cookie
parameter to view the results of your search.
<res> <af_in_progress>true</af_in_progress> <af_first_result_af_took>0</af_first_result_af_took> <af_cookie>0-3b0a6076-47fa-4e6f-9b83-6fe3aa8f7079+2</af_cookie> <af_complete_percentage>0</af_complete_percentage> <bucket_info> <minute_points>200</minute_points> <daily_points>25000</daily_points> <minute_points_remaining>190</minute_points_remaining> <daily_points_remaining>24980</daily_points_remaining> <minute_bucket_start>2016-02-24 16:17:54</minute_bucket_start> <daily_bucket_start>2016-02-24 16:11:28</daily_bucket_start> </bucket_info> </res>

Request Body Parameters

Use the following request body parameters when searching samples or sessions:
Parameters
Description
Type
Example or Possible Values
apiKey
(
Required
) API key tied to your license. All users attached to a license share a single API key.
string
Example (obfuscated):
d32108a5-XXX-XXXX-XXXX-c04bda5b8450
scope
(
Required
) Scope of the search. Only available and required for:
/samples/search/
.
string enumeration
Possible values:
private, public, global
size
Number of results to provide.
number
Possible values:
Range is 1-4000; however,
size
and
from
parameter values combined cannot exceed 4,000 total.
Default value: 50
from
Sample number from which to start.
number
The number when adding the
size
and
from
parameters cannot exceed 4000.
Default value: 0
sort
Sort based on the provided artifact. You can display sort results in ascending or descending order.
object
Possible values for sorting:
app_name, app_packagename, filetype, size, finish_date, create_date, update_date, md5, sha1, sha256, ssdeep
Possible values for
/sessions/search
:
app, device_country, device_countrycode, device_hostname, device_serial, vsys, dst_country, dst_countrycode, dst_ip, dst_port, emailsbjcharset, device_industry, src_country, src_countrycode, src_ip, src_port, sha256, tstamp, upload_src
Possible values for order:
asc, desc
Example:
"sort": { "filetype": { "order": "desc" }
type
By default, when you perform a search, AutoFocus displays all search results, up to 4,000, as they accumulate until the search is complete.
If you set
type
to
scan
, you can get up to 200,000 search results through pagination. Each time you view results, AutoFocus responds with the next page of results until the search is complete. By default, a page displays 50 results, and you can use the
size
parameter to set the number of results on each page. The
scan
value is currently the only possible value. For
type=scan
, the
from
and
sort
parameters are not available.
Only available for these JSON resources:
/samples/search/and /sessions/search/
.
object
Possible values:
scan
Example:
{ "apiKey":"apikey", "query":{       "operator":"all", "children":[ { "field":"sample.malware", "operator":"is", "value":1 } ] }, "size":10, "type": "scan", "scope":"public" }
query
Query based on conditions specified within this object.
object
See Search Field Names and Search Parameter Types and Operators for a list of available fields, operators, and acceptable values.
To easily determine your
query
, first run the equivalent search in the AutoFocus web portal and then use the
API Search
button to view the corresponding JSON.
field
Child parameter of
query
string enumeration
See Search Field Names for a list of available fields.
operator
Child parameter of
query
string enumeration
Possible values depend on the specified field. See Search Parameter Types and Operators for a list of available operators.
When you have more than one search or child search condition, you must specify an additional operator parameter to specify whether to match
all
or
any
of the search conditions. Possible values are:
all, any
For example, the following JSON searches for malware that is either an Adobe Flash file or and Android API:
{ "operator":"all", "children":[ { "field":"sample.malware", "operator":"is", "value":1 }, { "operator":"any", "children":[ { "field":"sample.filetype", "operator":"is", "value":"Adobe Flash File" }, { "field":"sample.filetype", "operator":"is", "value":"Android APK" } ] } ] }
value
Child parameter of
query
Type varies depending on the selected
field
and
operator
.
Possible values depending on the selected
field
and
operator
values. Use the
Export Search
button in the AutoFocus web portal to get the corresponding
value
for any search.

Recommended For You