Back

STIX

Search Overview

The search API is designed to help you find relevant STIX objects quickly and accurately. Just like searching on the web, you can use text, keywords, and key/value terms to narrow the results to just those in which you’re interested.

Pagination

Like the users, endpoint, STIX results are paginated via an HTTP Link header.

Searching

The main entry point for your STIX data is found at /api/stix/. It is here that you’ll search for STIX objects in your system.

GET api/stix/

CURL Example

curl
   'your-edge.com/api/stix/?{params}'
   -H "Authorization: Token user:token"

Paramters:

Name Type Description
q String A Full Text Search query field
type String Short form STIX Types (‘ind’, ‘cam’)
subtype String Indicator STIX Types (e.g. ‘IP Watchlist’)
tlp String TLP Color (white, green, amber, red)
ns String Namespace to search
year Integer Four digit year
month Integer Two digit month
day Integer two digit day

Protips!

  • All parameters can be used directly in the q string by using a : in place of the = sign. For example, ?type=cam&tlp=red would become ?q="tlp:red type:cam", and ?q=malware&year=2016 would be ?q="malware year:2016"
  • You can use the special flag __local__ to reference your local Soltra Edge instance’s namespace. e.g. ?ns=__local__.

Example Search:

All the parameters can be mixed and matched in order to narrow down the results. For instance, if you wanted to find all the objects in your system which reference the Nitro Campaign, are TLP AMBER, and were received in 2016, you could use the following query:

GET /api/stix/?q="nitro"&type=cam&year=2016&tlp=amber

Response:

{
    "estimate": 30,
    "took": 0.64961,
    "hits": [
        {
            "id": "edge:campaign-721976f9-56d7-4749-8c69-b3ac7c315f05",
            "type": "cam",
            "etlp": "AMBER",
            "title": "Nitro",
            "description": null,
            "uploaded_by": "User123",
            "uploaded_on": "2016-10-17T14:23:56",
            "children_types": [
                [
                    "ttp",
                    120
                ],
                [
                    "act",
                    1
                ]
            ],
            "tags": [],
            "url": "http://192.168.1.10:8000/api/stix/edge%3Acampaign-721976f9-56d7-4749-8c69-b3ac7c315f05/"
        },
        ...
    ]
}

This pulls back an estimate of the total hits, the time it took to complete the query, and a list of search hits. Each item in the hits list contains a short summary of the STIX object. You can get the full details and all of its related nodes by following the link in the url key.

Retrieve a single STIX object

GET /stix/{id}/

CURL Example

curl
   'your-edge.com/api/stix/{id}/'
   -H "Authorization: Token user:token"

Headers

Name Description
X-PSTD-VERSION The PythonStix output version e.g. 1.1.1.3

Response:

{
    "id": "coolranch:indicator-ef4474da-0c13-4680-b935-b7b46218daaf",
    "url": "http://192.168.1.10:8000/api/stix/coolranch%3Aindicator-ef4474da-0c13-4680-b935-b7b46218daaf/",
    "created_on": "2016-10-17T20:54:19.886000",
    "type": "indicator",
    "tlp": "WHITE",
    "document": {
        "stix_header": {
            "handling": [
                {
                    "controlled_structure": "../../../../descendant-or-self::node() | ../../../../descendant-or-self::node()/@*",
                    "marking_structures": [
                        {
                            "color": "WHITE",
                            "xsi:type": "tlpMarking:TLPMarkingStructureType"
                        }
                    ]
                }
            ]
        },
        "timestamp": "2016-10-17T20:54:30.963909+00:00",
        "ttps": {
            "ttps": [
                {
                    "description": "Long Description",
                    "title": "Sample TTP",
                    "timestamp": "2016-10-17T20:52:39.359148+00:00",
                    "behavior": {
                        "malware_instances": [
                            {
                                "xsi:type": null,
                                "names": [
                                    "Sample Dialer Malware"
                                ],
                                "types": [
                                    {
                                        "xsi:type": "stixVocabs:MalwareTypeVocab-1.0",
                                        "value": "Dialer"
                                    }
                                ],
                                "title": "Sample Malware"
                            }
                        ]
                    },
                    "short_description": "Short Description",
                    "id": "coolranch:ttp-5f8a991d-7f0a-4e42-a918-5ff4ef60e7a1"
                }
            ]
        },
        "version": "1.1.1",
        "indicators": [
            {
                "observable": {
                    "idref": "coolranch:observable-baafe968-bfbc-404d-9211-6fd5767741e0"
                },
                "confidence": {
                    "timestamp": "2016-10-17T20:54:19.878332+00:00",
                    "value": {
                        "xsi:type": "stixVocabs:HighMediumLowVocab-1.0",
                        "value": "Medium"
                    }
                },
                "handling": [
                    {
                        "controlled_structure": "../../../descendant-or-self::node() | ../../../descendant-or-self::node()/@*",
                        "marking_structures": [
                            {
                                "color": "WHITE",
                                "xsi:type": "tlpMarking:TLPMarkingStructureType"
                            }
                        ]
                    }
                ],
                "description": "A long description",
                "indicator_types": [
                    {
                        "xsi:type": "stixVocabs:IndicatorTypeVocab-1.1",
                        "value": "IP Watchlist"
                    }
                ],
                "title": "Sample Indicator",
                "timestamp": "2016-10-17T20:54:19.878296+00:00",
                "indicated_ttps": [
                    {
                        "ttp": {
                            "idref": "coolranch:ttp-5f8a991d-7f0a-4e42-a918-5ff4ef60e7a1"
                        }
                    }
                ],
                "short_description": "A short Description",
                "id": "coolranch:indicator-ef4474da-0c13-4680-b935-b7b46218daaf"
            }
        ],
        "observables": {
            "observables": [
                {
                    "id": "coolranch:observable-baafe968-bfbc-404d-9211-6fd5767741e0",
                    "observable_composition": {
                        "operator": "OR",
                        "observables": [
                            {
                                "idref": "coolranch:observable-2bdfd055-64fd-46e4-8f63-8d59524396af"
                            }
                        ]
                    }
                },
                {
                    "description": "Bad hosts",
                    "object": {
                        "id": "coolranch:hostname-d65b62bd-67d0-48f6-bf22-5f1333f2490e",
                        "properties": {
                            "xsi:type": "HostnameObjectType",
                            "hostname_value": "http://bad-guy-host.com"
                        }
                    },
                    "id": "coolranch:observable-2bdfd055-64fd-46e4-8f63-8d59524396af",
                    "title": "Hostname : http://bad-guy-host.com"
                }
            ],
            "major_version": 2,
            "update_version": 0,
            "minor_version": 1
        },
        "id": "edge:Package-a8cf1b14-fd0a-447f-9846-94f644196dbc"
    },
    "related": {
        "url": "http://192.168.1.10:8000/api/stix/coolranch%3Aindicator-ef4474da-0c13-4680-b935-b7b46218daaf/related/",
        "related_observables_url": "http://192.168.1.10:8000/api/stix/coolranch%3Aindicator-ef4474da-0c13-4680-b935-b7b46218daaf/related/observables",
        "related_ttps_url": "http://192.168.1.10:8000/api/stix/coolranch%3Aindicator-ef4474da-0c13-4680-b935-b7b46218daaf/related/ttps"
    }
}

The document node contains the full output of Python stix’ to_dict() with all Markings, Handlings, and Related objects embedded. The version of the object schema can be found via the X-PSTD-VERSION header.

The related section provided links to all STIX objects related to the current one

Output Formats

The format of the STIX document is controlled via the Accept header in your request.

Content-Type Description
application/jso n A JSON output containing the full stix document along with meta data and links (Default)
application/xml XML output containing the full stix document along with meta data and link urls
application/vnd .soltra.raw+jso n A JSON dump of just the Python STIX object
application/vnd .soltra.raw+xml A XML Python STIX package containing your object

Upload STIX Package

You can upload XML files containing STIX Packages by POST ing the file contents to the /api/upload endpoint.

POST /api/upload/

CURL Example

curl
   -XPOST
   'your-edge.com/api/upload/'
   -H "Authorization: Token user:token"
   -F file=@/path/to/package.xml

Response

{
    "link": "/api/tasks/0c71d1b9-88e8-45b5-a96c-cea358052b05/"
}

Note that the upload process is asynchronous. So, what you get back after your submission is a link to where you can poll the progress of the current task.

To check the status of your upload, use the provided link.

curl
   'your-edge.com/api/tasks/0c71d1b9-88e8-45b5-a96c-cea358052b05/'
   -H "Authorization: Token user:token"

Response

{
    "resource_id": "581366bd0fada635a56382e6",
    "started_on": "2016-10-28T14:54:53.843",
    "state": "success",
    "link": "/api/stix/?upload=581366bd0fada635a56382e6",
    "message": "inbox: submitted package(581366bd0fada635a56382e6), objects(6), elapsed(73.79 ms)",
    "type": "UPLOAD",
    "id": "6b861679-8b0d-4ed3-8d62-d2cda5a7da72"
}

When the task is complete, the link value will be populated with a URL where you may browse your newly uploaded STIX content.

Note: In the event of an error, the state field will report FAILED. The exact reason for the failure will be provided in the message section of the response.

 

For more information, join the conversation in the Soltra Edge Forums at forums.soltra.com.