Client library to simplify interacting with the PolySwarm consumer API
Project description
Table of Contents
polyswarm-api
An interface to the public and private PolySwarm APIs. For an easy-to-use CLI tool, or as an example of how to use these APIs, please see polyswarm-cli
Supports Python 2.7 and greater.
Dependencies
You may need to install your platforms' equivalent python-dev
package.
Installation
From PyPI:
pip install polyswarm-api
From source:
python setup.py install
Usage
Create an API Client
from polyswarm_api.api import PolyswarmAPI
api_key = "317b21cb093263b701043cb0831a53b9"
api = PolyswarmAPI(key=api_key)
Note: You will need to get your own API key from polyswarm.network/profile/apiKeys
Perform Scans
results = api.scan_directory("/path/to/directory")
results = api.scan("/path/to/eicar")
results = api.scan_urls("http://bad.com")
Perform Searches
results = api.search("275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f")
query = { "query": {
"exists": {
"field": "lief.libraries"
}
}
}
results = api.search_by_metadata(query)
Metadata Terms
The following is a non-exhaustive list of the terms currently supported by PolySwarm.
When searching, each nested level would be separated by .
, e.g. pefile.imphash
.
Names of fields are case-sensitive so take care to specify them correctly. The following list is non-exhaustive.
If there are more fields or tools you would like to see, please get in touch at info@polyswarm.io.
-
lief
- curatedlief
outputhas_nx
is_pie
libraries
- list of imported librariesentrypoint
- entrypoint in decimalvirtual_size
- virtual size in decimalexported_functions
- list of exported functionsimported_functions
- list of imported functions
-
pefile
- curatedpefile
outputis_dll
- booleanis_exe
- booleanexports
- exported functionsimphash
-imphash
of the fileimports
- dictionary of imports in formatdllname: [list, of, functions]
uses_cfg
- booleanuses_dep
- booleanuses_seh
- booleancompile_date
- booleanhas_import_table
- booleanhas_export_table
- booleanis_probably_packed
- booleanwarnings
- warnings from pefile parser
-
exiftool
-exiftool
output (fromexiftool -j
)MIMEType
- mimetype of the fileInternalName
- internal name extracted from executableOriginalFileName
- original name of the fileAuthor
- author of the fileTitle
- title of the fileSubject
- subject of the fileLanguageCode
- language used by executable (e.g. 'English (U.S.)')CharacterSet
- character set of fileLanguage
- language of file (e.g. 'en-GB')ModifyDate
- last modified time string from documentCreateDate
- creation time string from document- many more; view
exiftool
documentation for more info.
-
strings
- interesting statically-extracted stringsdomains
- observed domainsurls
- URLs (including things like emails)ipv4
- IPV4 addressesipv6
- IPV6 addresses
Allowed Query Searches
For query search, only a sub-set of Elasticsearch queries are allowed at the moment.
They are only allowed in the following simple form (not in the complete form with all other attributes) for security reasons.
To make command line searching easier, the default input format for the CLI is a query field that will be wrapped into a JSON query_string
request.
This is likely sufficient for most queries.
Do note: some characters, like backslashes, must be escaped with a backslash.
Query String
{
"query": {
"query_string": {
"query": "this AND that OR something:>10"
}
}
}
Check If Field Exists
{
"query": {
"exists": {
"field": "lief.libraries"
}
}
}
Note: Elasticsearch Exists Query.
Range Query
{
"query": {
"range": {
"age": {
"gte": 10,
"lte": 20
}
}
}
}
Note: Elasticsearch Range Query. These are specially interesting for date fields. You will find a reference on date math here.
**Note:** [Elasticsearch Query String](https://www.elastic.co/guide/en/elasticsearch/reference/6.7/query-dsl-query-string-query.html).
###### Simple Query String
```json
{
"query": {
"simple_query_string": {
"query": "\"fried eggs\" +(eggplant | potato) -frittata",
"fields": ["title^5", "body"],
"default_operator": "and"
}
}
}
Note: Elasticsearch Simple Query String.
Terms (Array) Query
{
"query": {
"terms": {
"user": ["kimchy", "elasticsearch"]
}
}
}
Note: Elasticsearch Terms Query.
Download Files
results = api.download("download/", "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f")
Perform Hunts
response = api.live(open("eicar.yara").read())
results = api.live_results(hunt_id=response.result.id)
response = api.historical(open("eicar.yara").read())
results = api.historical_results(hunt_id=response.result.id)
Perform Rescans
results = api.rescan("275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f")
Get a Stream
results = api.stream(destination_dir="/my/malware/path")
Questions? Problems?
File a ticket or email us at info@polyswarm.io
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for polyswarm_api-1.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0703b97c11ae7ac7ecb420179f62b5d2531f612e61b93115ceb80c8a96fbe806 |
|
MD5 | 792cc1e0af0cb55b731be77ec0fa59a1 |
|
BLAKE2b-256 | 93fe5221c2e0eef9f5d186d9f7e4a4ba6e425dfd801d0f8e1f11016713a473e4 |