Indicator¶

Contents

Indicator

Summary¶

Resource	Operation	Description
Indicator	POST /api/indicators	Creates a new indicator.
	POST /api/indicators/bulk	Creates a list of new indicators.
	POST /api/indicators/(int:a_id)/(int:b_id)/equal	Creates an equal to relationship between two indicators.
	GET /api/indicators/(int:indicator_id)	Gets a single indicator given its ID.
	GET /api/indicators	Gets a gzip compressed list of indicators based on various filter criteria.
	PUT /api/indicators/(indicator_id)	Updates an existing indicator.
	DELETE /api/indicators/(indicator_id)	Deletes an indicator.
	DELETE /api/indicators/(int:a_id)/(int:b_id)/equal	Deletes an equal to relationship between two indicators.

Create¶

JSON Schema

Required parameters are in bold.

NOTE: While only type and value are listed as required parameters, confidence, impact, and status are also required. However, these three parameters are omitted from the required list of fields because SIP will use the default values you chose when you initially setup and configured SIP. The final requirement not listed in the schema is that you must either supply the username parameter OR your API key in the Authorization header. This is what is used to link the indicator to the user who created it.

SIP comes with a list of reasonable values that are added to the database during its initial setup. For example, the default confidence chosen is “LOW”, impact is “LOW”, and status is “NEW”.

type	object
properties
campaigns	type	array
	items
		type	string
		maxLength	255
		minLength	1
	minItems	1
case_sensitive	type	boolean
confidence	type	string
	maxLength	255
	minLength	1
impact	type	string
	maxLength	255
	minLength	1
references	type	array
	items
		type	object
		properties
		source	type	string
			maxLength	255
			minLength	1
		reference	type	string
			maxLength	512
			minLength	1
		additionalProperties	False
	minItems	1
status	type	string
	maxLength	255
	minLength	1
substring	type	boolean
tags	type	array
	items
		type	string
		maxLength	255
		minLength	1
	minItems	1
type	type	string
	maxLength	255
	minLength	1
username	type	string
	maxLength	255
	minLength	1
value	type	string
	maxLength	512
	minLength	1
additionalProperties	False

POST /api/indicators¶

Creates a new indicator.

Example request:

POST /indicators HTTP/1.1
Host: 127.0.0.1
Content-Type: application/json

{
  "campaigns": ["LOLcats", "Derpsters"],
  "case_sensitive": false,
  "confidence": "LOW",
  "impact": "LOW",
  "references": [
    {
      "source": "Your company",
      "reference": "http://yourwiki.com/page-for-the-event"
    },
    {
      "source": "OSINT",
      "reference": "http://somehelpfulblog.com/malware-analysis"
    }
  ],
  "status": "NEW",
  "substring": false,
  "tags": ["phish", "from_address"],
  "type": "Email - Address",
  "username": "your_SIP_username",
  "value": "badguy@evil.com"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "all_children": [],
  "all_equal": [],
  "campaigns": [
    {
      "aliases": [],
      "created_time": "Thu, 28 Feb 2019 17:10:44 GMT",
      "id": 1,
      "modified_time": "Thu, 28 Feb 2019 17:10:44 GMT",
      "name": "LOLcats"
    },
    {
      "aliases": [],
      "created_time": "Fri, 01 Mar 2019 17:58:45 GMT",
      "id": 2,
      "modified_time": "Fri, 01 Mar 2019 17:58:45 GMT",
      "name": "Derpsters"
    }
  ],
  "case_sensitive": false,
  "children": [],
  "confidence": "LOW",
  "created_time": "Fri, 01 Mar 2019 18:00:51 GMT",
  "equal": [],
  "id": 1,
  "impact": "LOW",
  "modified_time": "Fri, 01 Mar 2019 18:00:51 GMT",
  "parent": null,
  "references": [
    {
      "id": 1,
      "reference": "http://yourwiki.com/page-for-the-event",
      "source": "Your company",
      "user": "your_SIP_username"
    },
    {
      "id": 3,
      "reference": "http://somehelpfulblog.com/malware-analysis",
      "source": "OSINT",
      "user": "your_SIP_username"
    }
  ],
  "status": "NEW",
  "substring": false,
  "tags": ["from_address", "phish"],
  "type": "Email - Address",
  "user": "your_SIP_username",
  "value": "badguy@evil.com"
}

Request Headers

Authorization – Optional Apikey value

Response Headers

Content-Type – application/json

Status Codes

201 Created – Indicator created
400 Bad Request – Confidence not given and no default to select
400 Bad Request – Impact not given and no default to select
400 Bad Request – Status not given and no default to select
400 Bad Request – JSON does not match the schema
401 Unauthorized – Invalid role to perform this action
401 Unauthorized – Username is inactive
401 Unauthorized – You must supply either username or API key
404 Not Found – Campaign not found
404 Not Found – Confidence not found
404 Not Found – Impact not found
404 Not Found – Reference not found
404 Not Found – Status not found
404 Not Found – Tag not found
404 Not Found – Type not found
404 Not Found – User not found by API key
404 Not Found – Username not found
409 Conflict – Indicator already exists

Create Multiple¶

JSON Schema

NOTE: This API route follows the same rules and logic as the standard Create route with the one exception being that duplicate indicators are ignored and skipped instead of returning a 409 status. The only difference in the JSON schema is that you specify a list of indicators under the indicators key.

type	object
properties
indicators	type	array
	items
		type	object
		properties
		campaigns	type	array
			items
				type	string
				maxLength	255
				minLength	1
			minItems	1
		case_sensitive	type	boolean
		confidence	type	string
			maxLength	255
			minLength	1
		impact	type	string
			maxLength	255
			minLength	1
		references	type	array
			items
				type	object
				properties
				source	type	string
					maxLength	255
					minLength	1
				reference	type	string
					maxLength	512
					minLength	1
				additionalProperties	False
			minItems	1
		status	type	string
			maxLength	255
			minLength	1
		substring	type	boolean
		tags	type	array
			items
				type	string
				maxLength	255
				minLength	1
			minItems	1
		type	type	string
			maxLength	255
			minLength	1
		username	type	string
			maxLength	255
			minLength	1
		value	type	string
			maxLength	512
			minLength	1
		additionalProperties	False
	minItems	1
additionalProperties	False

POST /api/indicators/bulk¶

Creates a list of new indicators.

Example request:

POST /indicators/bulk HTTP/1.1
Host: 127.0.0.1
Content-Type: application/json

{
  "indicators": [
    {
      "campaigns": ["LOLcats", "Derpsters"],
      "case_sensitive": false,
      "confidence": "LOW",
      "impact": "LOW",
      "references": [
        {
          "source": "Your company",
          "reference": "http://yourwiki.com/page-for-the-event"
        },
        {
          "source": "OSINT",
          "reference": "http://somehelpfulblog.com/malware-analysis"
        }
      ],
      "status": "NEW",
      "substring": false,
      "tags": ["phish", "from_address"],
      "type": "Email - Address",
      "username": "your_SIP_username",
      "value": "badguy@evil.com"
    },
    {
      "campaigns": ["LOLcats", "Derpsters"],
      "case_sensitive": false,
      "confidence": "LOW",
      "impact": "LOW",
      "references": [
        {
          "source": "Your company",
          "reference": "http://yourwiki.com/page-for-the-event"
        },
        {
          "source": "OSINT",
          "reference": "http://somehelpfulblog.com/malware-analysis"
        }
      ],
      "status": "NEW",
      "substring": false,
      "tags": ["phish", "reply_to_address"],
      "type": "Email - Address",
      "username": "your_SIP_username",
      "value": "mastermind@evil.com"
    }
  ]
}

Example response:

HTTP/1.1 204 No Content

Request Headers

Authorization – Optional Apikey value

Response Headers

Content-Type – application/json

Status Codes

204 No Content – Indicators created
400 Bad Request – Confidence not given and no default to select
400 Bad Request – Impact not given and no default to select
400 Bad Request – Status not given and no default to select
400 Bad Request – JSON does not match the schema
401 Unauthorized – Invalid role to perform this action
401 Unauthorized – Username is inactive
401 Unauthorized – You must supply either username or API key
404 Not Found – Campaign not found
404 Not Found – Confidence not found
404 Not Found – Impact not found
404 Not Found – Reference not found
404 Not Found – Status not found
404 Not Found – Tag not found
404 Not Found – Type not found
404 Not Found – User not found by API key
404 Not Found – Username not found

Create Equal To Relationship¶

Indicators can be directly or indirectly equal to one another, as the relationships follow the transitive property. If you make indicator 1 equal to indicator 2, and then make indicator 2 equal to indicator 3, then indicators 1 and 3 will be indirectly equal.

The “equal” list contains the directly equal indicator IDs.

The “all_equal” list contains directly and indirectly equal indicator IDs.

JSON Schema

type

null

POST /api/indicators/(int: a_id)/(int: b_id)/equal¶

Creates an equal to relationship between two indicators.

Example request:

POST /indicators/1/2/equal HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content

Request Headers

Authorization – Optional Apikey value

Response Headers

Content-Type – application/json

Status Codes

204 No Content – Relationship created
400 Bad Request – Cannot make indicator equal to itself
400 Bad Request – JSON does not match the schema
401 Unauthorized – Invalid role to perform this action
404 Not Found – Indicator ID not found
409 Conflict – The indicators are already directly or indirectly equal

Create Parent/Child Relationship¶

Indicators can have multiple child indicators, but only a single parent indicator.

The “children” list contains the first-generation child indicator IDs.

The “all_children” list contains first-generation and beyond child indicator IDs.

JSON Schema

type

null

POST /api/indicators/(int: parent_id)/(int: child_id)/relationship¶

Creates a parent/child relationship between two indicators.

Example request:

POST /indicators/1/2/relationship HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content

Request Headers

Authorization – Optional Apikey value

Response Headers

Content-Type – application/json

Status Codes

204 No Content – Relationship created
400 Bad Request – Cannot add an indicator to its own children
400 Bad Request – Child indicator already has a parent
400 Bad Request – JSON does not match the schema
401 Unauthorized – Invalid role to perform this action
404 Not Found – Indicator ID not found

Read Single¶

GET /api/indicators/(int: indicator_id)¶

Gets a single indicator given its ID.

Example request:

GET /indicators/1 HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "all_children": [],
  "all_equal": [],
  "campaigns": [
    {
      "aliases": [],
      "created_time": "Thu, 28 Feb 2019 17:10:44 GMT",
      "id": 1,
      "modified_time": "Thu, 28 Feb 2019 17:10:44 GMT",
      "name": "LOLcats"
    },
    {
      "aliases": [],
      "created_time": "Fri, 01 Mar 2019 17:58:45 GMT",
      "id": 2,
      "modified_time": "Fri, 01 Mar 2019 17:58:45 GMT",
      "name": "Derpsters"
    }
  ],
  "case_sensitive": false,
  "children": [],
  "confidence": "LOW",
  "created_time": "Fri, 01 Mar 2019 18:00:51 GMT",
  "equal": [],
  "id": 1,
  "impact": "LOW",
  "modified_time": "Fri, 01 Mar 2019 18:00:51 GMT",
  "parent": null,
  "references": [
    {
      "id": 1,
      "reference": "http://yourwiki.com/page-for-the-event",
      "source": "Your company",
      "user": "your_SIP_username"
    },
    {
      "id": 3,
      "reference": "http://somehelpfulblog.com/malware-analysis",
      "source": "OSINT",
      "user": "your_SIP_username"
    }
  ],
  "status": "NEW",
  "substring": false,
  "tags": ["from_address", "phish"],
  "type": "Email - Address",
  "user": "your_SIP_username",
  "value": "badguy@evil.com"
}

Request Headers

Authorization – Optional Apikey value

Response Headers

Content-Type – application/json

Status Codes

200 OK – Indicator found
401 Unauthorized – Invalid role to perform this action
404 Not Found – Indicator ID not found

Read Multiple¶

GET /api/indicators¶

Gets a gzip compressed list of indicators based on various filter criteria.

NOTE: Multiple query parameters can be used and will be applied with AND logic. The default logic for query parameters that accept a comma-separated list of values is also AND. However, there are some parameters listed below that support the use of OR logic instead. Simply include the string “[OR]” within the parameter’s value.

Get indicators that have both intel sources A *AND* B:

GET /indicators?sources=A,B HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Get indicators that have either intel source A *OR* B:

GET /indicators?sources=[OR]A,B HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example request:

GET /indicators?value=evil.com&status=NEW HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Type: application/json

[
  {
    "id": 1,
    "type": "Email - Address",
    "value": "badguy@evil.com"
  }
]

Request Headers

Authorization – Optional Apikey value

Response Headers

Content-Type – application/json

Query Parameters

case_sensitive – True/False
confidence – Confidence value
count – Flag to return the number of results rather than the results themselves
created_after – Parsable date or datetime in GMT. Ex: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
created_before – Parsable date or datetime in GMT. Ex: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
exact_value – Exact indicator value to find. Does not use a wildcard search.
impact – Impact value
modified_after – Parsable date or datetime in GMT. Ex: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
modified_before – Parsable date or datetime in GMT. Ex: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
no_campaigns – Flag to search for indicators without any campaigns
no_references – Flag to search for indicators without any references
no_tags – Flag to search for indicators without any tags
not_sources – Comma-separated list of intel sources to EXCLUDE
not_tags – Comma-separated list of tags to EXCLUDE
not_users – Comma-separated list of usernames to EXCLUDE from the references
reference – Intel reference value
sources – Comma-separated list of intel sources. Supports [OR].
status – Status value
substring – True/False
tags – Comma-separated list of tags. Supports [OR].
type – Type value
types – Comma-separated list of types. Only supports OR logic since indicators only have one type.
user – Username of person who created the associated reference
users – Comma-separated list of usernames of the associated references. Supports [OR].
value – String found in value (uses wildcard search)

Status Codes

200 OK – Indicators found
401 Unauthorized – Invalid role to perform this action

Update¶

JSON Schema

Required parameters are in bold.

type	object
properties
campaigns	type	array
	items
		type	string
		maxLength	255
		minLength	1
	minItems	1
case_sensitive	type	boolean
confidence	type	string
	maxLength	255
	minLength	1
impact	type	string
	maxLength	255
	minLength	1
references	type	array
	items
		type	object
		properties
		source	type	string
			maxLength	255
			minLength	1
		reference	type	string
			maxLength	512
			minLength	1
		additionalProperties	False
	minItems	1
status	type	string
	maxLength	255
	minLength	1
substring	type	boolean
tags	type	array
	items
		type	string
		maxLength	255
		minLength	1
	minItems	1
username	type	string
	maxLength	255
	minLength	1
additionalProperties	False

PUT /api/indicators/(indicator_id)¶

Updates an existing indicator.

Example request:

PUT /indicators/1 HTTP/1.1
Host: 127.0.0.1
Content-Type: application/json

{
  "confidence": "HIGH",
  "status": "ENABLED"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "all_children": [],
  "all_equal": [],
  "campaigns": [
    {
      "aliases": [],
      "created_time": "Thu, 28 Feb 2019 17:10:44 GMT",
      "id": 1,
      "modified_time": "Thu, 28 Feb 2019 17:10:44 GMT",
      "name": "LOLcats"
    },
    {
      "aliases": [],
      "created_time": "Fri, 01 Mar 2019 17:58:45 GMT",
      "id": 2,
      "modified_time": "Fri, 01 Mar 2019 17:58:45 GMT",
      "name": "Derpsters"
    }
  ],
  "case_sensitive": false,
  "children": [],
  "confidence": "HIGH",
  "created_time": "Fri, 01 Mar 2019 18:00:51 GMT",
  "equal": [],
  "id": 1,
  "impact": "LOW",
  "modified_time": "Fri, 01 Mar 2019 13:37:02 GMT",
  "parent": null,
  "references": [
    {
      "id": 1,
      "reference": "http://yourwiki.com/page-for-the-event",
      "source": "Your company",
      "user": "your_SIP_username"
    },
    {
      "id": 3,
      "reference": "http://somehelpfulblog.com/malware-analysis",
      "source": "OSINT",
      "user": "your_SIP_username"
    }
  ],
  "status": "ENABLED",
  "substring": false,
  "tags": ["from_address", "phish"],
  "type": "Email - Address",
  "user": "your_SIP_username",
  "value": "badguy@evil.com"
}

Request Headers

Authorization – Optional Apikey value

Response Headers

Content-Type – application/json

Status Codes

200 OK – Indicator updated
400 Bad Request – JSON does not match the schema
401 Unauthorized – Invalid role to perform this action
401 Unauthorized – Username is inactive
404 Not Found – Campaign not found
404 Not Found – Confidence not found
404 Not Found – Impact not found
404 Not Found – Indicator ID not found
404 Not Found – Reference not found
404 Not Found – Status not found
404 Not Found – Tag not found
404 Not Found – Username not found

Delete¶

DELETE /api/indicators/(indicator_id)¶

Deletes an indicator.

Example request:

DELETE /indicators/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content

Request Headers

Authorization – Optional Apikey value

Status Codes

204 No Content – Indicator deleted
401 Unauthorized – Invalid role to perform this action
404 Not Found – Indicator ID not found
409 Conflict – Unable to delete indicator due to foreign key constraints

Delete Equal To Relationship¶

Two indicators must be directly equal in order to delete the relationship.

DELETE /api/indicators/(int: a_id)/(int: b_id)/equal¶

Deletes an equal to relationship between two indicators.

Example request:

DELETE /indicators/1/2/equal HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content

Request Headers

Authorization – Optional Apikey value

Status Codes

204 No Content – Relationship deleted
400 Bad Request – Indicator IDs must be different
401 Unauthorized – Invalid role to perform this action
404 Not Found – Indicator ID not found
404 Not Found – Relationship does not exist or the indicators are not directly equal

Delete Parent/Child Relationship¶

The child indicator must be first-generation in order to delete the relationship.

DELETE /api/indicators/(int: parent_id)/(int: child_id)/relationship¶

Deletes an indicator parent/child relationship.

Example request:

DELETE /indicators/1/2/relationship HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content

Request Headers

Authorization – Optional Apikey value

Status Codes

204 No Content – Relationship deleted
400 Bad Request – Parent and child indicators must be different
401 Unauthorized – Invalid role to perform this action
404 Not Found – Indicator ID not found
404 Not Found – Relationship does not exist

Indicator¶

Summary¶

Create¶

Create Multiple¶

Create Equal To Relationship¶

Create Parent/Child Relationship¶

Read Single¶

Read Multiple¶

Update¶

Delete¶

Delete Equal To Relationship¶

Delete Parent/Child Relationship¶

SIP

Navigation

Related Topics