Simple Intel Platform

Documentation Status

What is SIP?

SIP is a Dockerized threat intelligence platform for managing security events, indicators, and the relationships between them. It is designed for ease of use and a low barrier of entry so that anyone can quickly deploy a production-ready intel platform for their organization.

At its core, SIP is a RESTful API sitting atop a database that has been carefully designed to hold the information we have found over the years to be the most impactful in developing a successful threat intelligence program.

Why use SIP?

Security is not easy. It is not enough to simply purchase the Latest And Greatest™ product and believe that your organization is protected. There is an endless supply of financially-motivated attackers, and their techniques are always evolving.

The best way to protect your organization is to ensure that you learn something from every attack that you detect and feed that knowledge back into your detection tools. This is the detection+intel feedback loop, and mastering it is key to building an effective intel program for your organization.

SIP is the product of years worth of hands-on experience and insight from some of the most successful security and intel teams and was built with the hope that sharing this experience makes us all more secure.

Getting Started

  1. Setup SIP

  2. Use the included scripts to start and stop SIP

  3. Access the SIP API

  4. Access the SIP GUI

API

DEV: https://127.0.0.1:4443/api

PRODUCTION: https://127.0.0.1/api

Campaign

Summary

Resource

Operation

Description

Campaign

POST /api/campaigns

Creates a new campaign.

GET /api/campaigns/(int:campaign_id)

Gets a single campaign given its ID.

GET /api/campaigns

Gets a list of all the campaigns.

PUT /api/campaigns/(int:campaign_id)

Updates an existing campaign.

DELETE /api/campaigns/(int:campaign_id)

Deletes a campaign.
Create

JSON Schema

Required parameters are in bold.

type

object

properties

  • name

type

string

maxLength

255

minLength

1

  • aliases

type

array

items

type

string

maxLength

255

minLength

1

minItems

1

additionalProperties

False

POST /api/campaigns

Creates a new campaign.

Example request:

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

{
  "name": "LOLcats",
  "aliases": ["icanhaz"]
}

Example response:

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

{
  "id": 1,
  "aliases": ["icanhaz"],
  "created_time": "Thu, 28 Feb 2019 17:10:44 GMT",
  "modified_time": "Thu, 28 Feb 2019 17:10:44 GMT",
  "name": "LOLcats"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/campaigns/(int: campaign_id)

Gets a single campaign given its ID.

Example request:

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

Example response:

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

{
  "id": 1,
  "aliases": ["icanhaz"],
  "created_time": "Thu, 28 Feb 2019 17:10:44 GMT",
  "modified_time": "Thu, 28 Feb 2019 17:10:44 GMT",
  "name": "LOLcats"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/campaigns

Gets a list of all the campaigns.

Example request:

GET /campaigns HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

[
  {
    "id": 1,
    "aliases": ["icanhaz"],
    "created_time": "Thu, 28 Feb 2019 17:10:44 GMT",
    "modified_time": "Thu, 28 Feb 2019 17:10:44 GMT",
    "name": "LOLcats"
  },
  {
    "id": 2,
    "aliases": [],
    "created_time": "Thu, 28 Feb 2019 17:11:37 GMT",
    "modified_time": "Thu, 28 Feb 2019 17:11:37 GMT",
    "name": "Derpsters"
  }
]
Request Headers
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • name

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/campaigns/(int: campaign_id)

Updates an existing campaign.

Example request:

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

{
  "name": "Derpsters",
}

Example response:

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

{
  "id": 1,
  "aliases": ["icanhaz"],
  "created_time": "Thu, 28 Feb 2019 17:10:44 GMT",
  "modified_time": "Thu, 28 Feb 2019 17:18:29 GMT",
  "name": "Derpsters"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/campaigns/(int: campaign_id)

Deletes a campaign.

Example request:

DELETE /campaigns/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

CampaignAlias

Summary

Resource

Operation

Description

CampaignAlias

POST /api/campaigns/alias

Creates a new campaign alias.

GET /api/campaigns/alias/(int:campaign_alias_id)

Gets a single campaign alias given its ID.

GET /api/campaigns/alias

Gets a list of all the campaign aliases.

PUT /api/campaigns/alias/(int:campaign_alias_id)

Updates an existing campaign alias.

DELETE /api/campaigns/alias/(int:campaign_alias_id)

Deletes an campaign alias.
Create

JSON Schema

Required parameters are in bold.

type

object

properties

  • alias

type

string

maxLength

255

minLength

1

  • campaign

type

string

maxLength

255

minLength

1

additionalProperties

False

POST /api/campaigns/alias

Creates a new campaign alias.

Example request:

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

{
  "alias": "icanhaz",
  "campaign": "LOLcats"
}

Example response:

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

{
  "id": 1,
  "alias": "icanhaz",
  "campaign": "LOLcats"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/campaigns/alias/(int: campaign_alias_id)

Gets a single campaign alias given its ID.

Example request:

GET /campaigns/alias/1 HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

{
  "id": 1,
  "alias": "icanhaz",
  "campaign": "LOLcats"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/campaigns/alias

Gets a list of all the campaign aliases.

Example request:

GET /campaigns/alias HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

[
  {
    "id": 1,
    "alias": "icanhaz",
    "campaign": "LOLcats"
  },
  {
    "id": 2,
    "alias": "Dino",
    "campaign": "Riders"
  }
]
Request Headers
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • alias

type

string

maxLength

255

minLength

1

  • campaign

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/campaigns/alias/(int: campaign_alias_id)

Updates an existing campaign alias.

Example request:

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

{
  "alias": "Dino",
  "campaign": "Riders"
}

Example response:

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

{
  "id": 1,
  "alias": "Dino",
  "campaign": "Riders"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/campaigns/alias/(int: campaign_alias_id)

Deletes a campaign alias.

Example request:

DELETE /campaigns/alias/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

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
Response Headers
Status Codes
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
Response Headers
Status Codes
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
Response Headers
Status Codes
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
Response Headers
Status Codes
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
Response Headers
Status Codes
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
Response Headers
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
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
Response Headers
Status Codes
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
Status Codes
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
Status Codes
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
Status Codes

IndicatorConfidence

Summary

Resource

Operation

Description

IndicatorConfidence

POST /api/indicators/confidence

Creates a new indicator confidence.

GET /api/indicators/confidence/(int:indicator_confidence_id)

Gets a single indicator confidence given its ID.

GET /api/indicators/confidence

Gets a list of all the indicator confidences.

PUT /api/indicators/confidence/(int:indicator_confidence_id)

Updates an existing indicator confidence.

DELETE /api/indicators/confidence/(int:indicator_confidence_id)

Deletes an indicator confidence.
Create

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

POST /api/indicators/confidence

Creates a new indicator confidence.

Example request:

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

{
  "value": "LOW"
}

Example response:

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

{
  "id": 1,
  "value": "LOW"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/indicators/confidence/(int: indicator_confidence_id)

Gets a single indicator confidence given its ID.

Example request:

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

Example response:

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

{
  "id": 1,
  "value": "LOW"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/indicators/confidence

Gets a list of all the indicator confidences.

Example request:

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

Example response:

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

[
  {
    "id": 1,
    "value": "LOW"
  },
  {
    "id": 2,
    "value": "HIGH"
  }
]
Request Headers
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/indicators/confidence/(int: indicator_confidence_id)

Updates an existing indicator confidence.

Example request:

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

{
  "value": "HIGH",
}

Example response:

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

{
  "id": 1,
  "value": "HIGH"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/indicators/confidence/(int: indicator_confidence_id)

Deletes an indicator confidence.

Example request:

DELETE /indicators/confidence/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

IndicatorImpact

Summary

Resource

Operation

Description

IndicatorImpact

POST /api/indicators/impact

Creates a new indicator impact.

GET /api/indicators/impact/(int:indicator_impact_id)

Gets a single indicator impact given its ID.

GET /api/indicators/impact

Gets a list of all the indicator impacts.

PUT /api/indicators/impact/(int:indicator_impact_id)

Updates an existing indicator impact.

DELETE /api/indicators/impact/(int:indicator_impact_id)

Deletes an indicator impact.
Create

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

POST /api/indicators/impact

Creates a new indicator impact.

Example request:

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

{
  "value": "LOW"
}

Example response:

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

{
  "id": 1,
  "value": "LOW"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/indicators/impact/(int: indicator_impact_id)

Gets a single indicator impact given its ID.

Example request:

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

Example response:

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

{
  "id": 1,
  "value": "LOW"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/indicators/impact

Gets a list of all the indicator impacts.

Example request:

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

Example response:

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

[
  {
    "id": 1,
    "value": "LOW"
  },
  {
    "id": 2,
    "value": "HIGH"
  }
]
Request Headers
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/indicators/impact/(int: indicator_impact_id)

Updates an existing indicator impact.

Example request:

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

{
  "value": "HIGH",
}

Example response:

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

{
  "id": 1,
  "value": "HIGH"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/indicators/impact/(int: indicator_impact_id)

Deletes an indicator impact.

Example request:

DELETE /indicators/impact/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

IndicatorStatus

Summary

Resource

Operation

Description

IndicatorStatus

POST /api/indicators/status

Creates a new indicator status.

GET /api/indicators/status/(int:indicator_status_id)

Gets a single indicator status given its ID.

GET /api/indicators/status

Gets a list of all the indicator statuses.

PUT /api/indicators/status/(int:indicator_status_id)

Updates an existing indicator status.

DELETE /api/indicators/status/(int:indicator_status_id)

Deletes an indicator status.
Create

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

POST /api/indicators/status

Creates a new indicator status.

Example request:

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

{
  "value": "New"
}

Example response:

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

{
  "id": 1,
  "value": "New"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/indicators/status/(int: indicator_status_id)

Gets a single indicator status given its ID.

Example request:

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

Example response:

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

{
  "id": 1,
  "value": "New"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/indicators/status

Gets a list of all the indicator statuses.

Example request:

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

Example response:

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

[
  {
    "id": 1,
    "value": "New"
  },
  {
    "id": 2,
    "value": "Informational"
  }
]
Request Headers
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/indicators/status/(int: indicator_status_id)

Updates an existing indicator status.

Example request:

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

{
  "value": "Informational",
}

Example response:

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

{
  "id": 1,
  "value": "Informational"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/indicators/status/(int: indicator_status_id)

Deletes an indicator status.

Example request:

DELETE /indicators/status/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

IndicatorType

Summary

Resource

Operation

Description

IndicatorType

POST /api/indicators/type

Creates a new indicator type.

GET /api/indicators/type/(int:indicator_type_id)

Gets a single indicator type given its ID.

GET /api/indicators/type

Gets a list of all the indicator types.

PUT /api/indicators/type/(int:indicator_type_id)

Updates an existing indicator type.

DELETE /api/indicators/type/(int:indicator_type_id)

Deletes an indicator type.
Create

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

POST /api/indicators/type

Creates a new indicator type.

Example request:

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

{
  "value": "Email - Address"
}

Example response:

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

{
  "id": 1,
  "value": "Email - Address"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/indicators/type/(int: indicator_type_id)

Gets a single indicator type given its ID.

Example request:

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

Example response:

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

{
  "id": 1,
  "value": "Email - Address"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/indicators/type

Gets a list of all the indicator types.

Example request:

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

Example response:

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

[
  {
    "id": 1,
    "value": "Email - Address"
  },
  {
    "id": 2,
    "value": "URI - Domain Name"
  }
]
Request Headers
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/indicators/type/(int: indicator_type_id)

Updates an existing indicator type.

Example request:

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

{
  "value": "URI - Domain Name",
}

Example response:

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

{
  "id": 1,
  "value": "URI - Domain Name"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/indicators/type/(int: indicator_type_id)

Deletes an indicator type.

Example request:

DELETE /indicators/type/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

IntelReference

Summary

Resource

Operation

Description

Indicator

GET /api/intel/reference/(int:intel_reference_id)/indicators

Gets a paginated list of the indicators associated with the intel reference.

IntelReference

POST /api/intel/reference

Creates a new intel reference.

GET /api/intel/reference/(int:intel_reference_id)

Gets a single intel reference given its ID.

GET /api/intel/reference

Gets a paginated list of all the intel references.

PUT /api/intel/reference/(int:intel_reference_id)

Updates an existing intel reference.

DELETE /api/intel/reference/(int:intel_reference_id)

Deletes an intel reference.
Create

JSON Schema

Required parameters are in bold.

NOTE: While only reference and source are listed as required parameters, there is a requirement not listed in the schema. You must either supply the username parameter OR your API key in the Authorization header. This is what is used to link the intel reference to the user who created it.

type

object

properties

  • reference

type

string

maxLength

512

minLength

1

  • source

type

string

maxLength

255

minLength

1

  • username

type

string

maxLength

255

minLength

1

additionalProperties

False

POST /api/intel/reference

Creates a new intel reference.

Example request:

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

{
  "reference": "http://yourwiki.com/page-for-the-event",
  "source": "Your company",
  "username": "your_SIP_username"
}

Example response:

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

{
  "id": 1,
  "reference": "http://yourwiki.com/page-for-the-event",
  "source": "Your company",
  "username": "your_SIP_username"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/intel/reference/(int: intel_reference_id)

Gets a single intel reference given its ID.

Example request:

GET /intel/reference/1 HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

{
  "id": 1,
  "reference": "http://yourwiki.com/page-for-the-event",
  "source": "Your company",
  "username": "your_SIP_username"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/intel/reference

Gets a paginated list of all the intel references.

Example request:

GET /intel/reference HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

{
  "_links": {
    "next": null,
    "prev": null,
    "self": "/api/intel/reference?page=1&per_page=10"
  },
  "_meta": {
    "page": 1,
    "per_page": 10,
    "total_items": 3,
    "total_pages": 1
  },
  "items": [
    {
      "id": 1,
      "reference": "http://yourwiki.com/page-for-the-event",
      "source": "Your company",
      "user": "your_SIP_username"
    },
    {
      "id": 2,
      "reference": "http://yourwiki.com/event2",
      "source": "Your company",
      "user": "your_SIP_username"
    },
    {
      "id": 3,
      "reference": "http://somehelpfulblog.com/malware-analysis",
      "source": "OSINT",
      "user": "your_SIP_username"
    }
  ]
}
Request Headers
Response Headers
Status Codes
Read Indicators
GET /api/intel/reference/(int: intel_reference_id)/indicators

Gets a paginated list of the indicators associated with the intel reference.

Example request:

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

Example response:

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

{
  "_links": {
    "next": null,
    "prev": null,
    "self": "/api/intel/reference/1/indicators?page=1&per_page=10"
  },
  "_meta": {
    "page": 1,
    "per_page": 10,
    "total_items": 1,
    "total_pages": 1
  },
  "items": [
    {
      "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": 2,
      "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
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • reference

type

string

maxLength

512

minLength

1

  • source

type

string

maxLength

255

minLength

1

  • username

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/intel/reference/(int: intel_reference_id)

Updates an existing intel reference.

Example request:

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

{
  "reference": "d41d8cd98f00b204e9800998ecf8427e"
}

Example response:

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

{
  "id": 1,
  "reference": "d41d8cd98f00b204e9800998ecf8427e",
  "source": "Your company",
  "username": "your_SIP_username"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/intel/reference/(int: intel_reference_id)

Deletes an intel reference.

Example request:

DELETE /intel/reference/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

IntelSource

Summary

Resource

Operation

Description

IntelSource

POST /api/intel/source

Creates a new intel source.

GET /api/intel/source/(int:intel_source_id)

Gets a single intel source given its ID.

GET /api/intel/source

Gets a list of all the intel sources.

PUT /api/intel/source/(int:intel_source_id)

Updates an existing intel source.

DELETE /api/intel/source/(int:intel_source_id)

Deletes an intel source.
Create

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

POST /api/intel/source

Creates a new intel source.

Example request:

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

{
  "value": "OSINT"
}

Example response:

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

{
  "id": 1,
  "value": "OSINT"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/intel/source/(int: intel_source_id)

Gets a single intel source given its ID.

Example request:

GET /intel/source/1 HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

{
  "id": 1,
  "value": "OSINT"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/intel/source

Gets a list of all the intel sources.

Example request:

GET /intel/source HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

[
  {
    "id": 1,
    "value": "OSINT"
  },
  {
    "id": 2,
    "value": "VirusTotal"
  }
]
Request Headers
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/intel/source/(int: intel_source_id)

Updates an existing intel source.

Example request:

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

{
  "value": "VirusTotal",
}

Example response:

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

{
  "id": 1,
  "value": "VirusTotal"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/intel/source/(int: intel_source_id)

Deletes an intel source.

Example request:

DELETE /intel/source/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

Role

Summary

Resource

Operation

Description

Role

POST /api/roles

Creates a new role. Requires the admin role.

GET /api/roles/(int:role_id)

Gets a single role given its ID.

GET /api/roles

Gets a list of all the roles.

PUT /api/roles/(int:role_id)

Updates an existing role. Requires the admin role.

DELETE /api/roles/(int:role_id)

Deletes a role. Requires the admin role.
Create

JSON Schema

Required parameters are in bold.

type

object

properties

  • name

type

string

maxLength

80

minLength

1

  • description

type

string

maxLength

255

minLength

1

additionalProperties

False

POST /api/roles

Creates a new role. Requires the admin role.

Example request:

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

{
  "name": "analyst",
  "description": "Users that create and process intel"
}

Example response:

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

{
  "id": 1,
  "name": "analyst",
  "description": "Users that create and process intel"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/roles/(int: role_id)

Gets a single role given its ID.

Example request:

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

Example response:

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

{
  "id": 1,
  "name": "analyst",
  "description": "Users that create and process intel"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/roles

Gets a list of all the roles.

Example request:

GET /roles HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

[
  {
    "id": 1,
    "name": "analyst",
    "description": "Users that create and process intel"
  },
  {
    "id": 2,
    "name": "readonly",
    "description": "Users that can only read the database"
  }
]
Request Headers
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • name

type

string

maxLength

80

minLength

1

  • description

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/roles/(int: role_id)

Updates an existing role. Requires the admin role.

Example request:

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

{
  "name": "intelusers"
}

Example response:

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

{
  "id": 1,
  "name": "intelusers",
  "description": "Users that create and process intel"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/roles/(int: role_id)

Deletes a role. Requires the admin role.

Example request:

DELETE /roles/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

Tag

Summary

Resource

Operation

Description

Tag

POST /api/tags

Creates a new tag.

GET /api/tags/(int:tag_id)

Gets a single tag given its ID.

GET /api/tags

Gets a list of all the tags.

PUT /api/tags/(int:tag_id)

Updates an existing tag.

DELETE /api/tags/(int:tag_id)

Deletes a tag.
Create

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

POST /api/tags

Creates a new tag.

Example request:

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

{
  "value": "phish"
}

Example response:

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

{
  "id": 1,
  "value": "phish"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/tags/(int: tag_id)

Gets a single tag given its ID.

Example request:

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

Example response:

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

{
  "id": 1,
  "value": "phish"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/tags

Gets a list of all the tags.

Example request:

GET /tags HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

[
  {
    "id": 1,
    "value": "phish"
  },
  {
    "id": 2,
    "value": "from_address"
  }
]
Request Headers
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • value

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/tags/(int: tag_id)

Updates an existing tag.

Example request:

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

{
  "value": "from_address",
}

Example response:

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

{
  "id": 1,
  "value": "from_address"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/tags/(int: tag_id)

Deletes a tag.

Example request:

DELETE /tags/1 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

User

Summary

Resource

Operation

Description

User

POST /api/users

Creates a new user. Requires the admin role.

GET /api/users/(int:user_id)

Gets a single user given its ID.

GET /api/users

Gets a list of all the users.

PUT /api/users/(int:user_id)

Updates an existing user. Requires the admin role.

DELETE /api/users/(int:user_id)

Deletes a user. Requires the admin role.
Create

JSON Schema

Required parameters are in bold.

type

object

properties

  • email

type

string

maxLength

255

minLength

1

  • first_name

type

string

maxLength

50

minLength

1

  • last_name

type

string

maxLength

50

minLength

1

  • password

type

string

minLength

1

  • roles

type

array

items

type

string

maxLength

80

minLength

1

minItems

1

  • username

type

string

maxLength

255

minLength

1

additionalProperties

False

POST /api/users

Creates a new user. Requires the admin role.

Example request:

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

{
  "email": "johndoe@company.com",
  "first_name": "John",
  "last_name": "Doe",
  "password": "asdfasdfasdf",
  "roles": ["analyst"],
  "username": "johndoe"
}

Example response:

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

{
  "active": true,
  "apikey": "11111111-1111-1111-1111-111111111111",
  "email": "johndoe@company.com",
  "first_name": "John",
  "id": 2,
  "last_name": "Doe",
  "roles": ["analyst"],
  "username": "johndoe"
}
Request Headers
Response Headers
Status Codes
Read Single
GET /api/users/(int: user_id)

Gets a single user given its ID.

Example request:

GET /users/2 HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

{
  "active": true,
  "email": "johndoe@company.com",
  "first_name": "John",
  "id": 2,
  "last_name": "Doe",
  "roles": ["analyst"],
  "username": "johndoe"
}
Request Headers
Response Headers
Status Codes
Read Multiple
GET /api/users

Gets a list of all the users.

Example request:

GET /users HTTP/1.1
Host: 127.0.0.1
Accept: application/json

Example response:

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

[
  {
    "active": true,
    "email": "admin@localhost",
    "first_name": "Admin",
    "id": 1,
    "last_name": "Admin",
    "roles": ["admin", "analyst"],
    "username": "admin"
  },
  {
    "active": true,
    "email": "johndoe@company.com",
    "first_name": "John",
    "id": 2,
    "last_name": "Doe",
    "roles": ["analyst"],
    "username": "johndoe"
  }
]
Request Headers
Response Headers
Status Codes
Update

JSON Schema

Required parameters are in bold.

type

object

properties

  • active

type

boolean

  • email

type

string

maxLength

255

minLength

1

  • first_name

type

string

maxLength

50

minLength

1

  • last_name

type

string

maxLength

50

minLength

1

  • password

type

string

minLength

1

  • roles

type

array

items

type

string

maxLength

80

minLength

1

minItems

1

  • username

type

string

maxLength

255

minLength

1

additionalProperties

False

PUT /api/users/(int: user_id)

Updates an existing user. Requires the admin role.

Example request:

PUT /users/2 HTTP/1.1
Host: 127.0.0.1
Content-Type: application/json

{
  "active": false
}

Example response:

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

{
  "active": false,
  "email": "johndoe@company.com",
  "first_name": "John",
  "id": 2,
  "last_name": "Doe",
  "roles": ["analyst"],
  "username": "johndoe"
}
Request Headers
Response Headers
Status Codes
Delete
DELETE /api/users/(int: user_id)

Deletes a user. Requires the admin role.

Example request:

DELETE /users/2 HTTP/1.1
Host: 127.0.0.1

Example response:

HTTP/1.1 204 No Content
Request Headers
Status Codes

GUI

SIP uses Flask-Admin for a basic web interface. Some of the functionality is restricted within the GUI for performance reasons, as SIP is primarily meant to be used via its API.

DEV: https://127.0.0.1:4443/SIP

PRODUCTION: https://127.0.0.1/SIP

Scripts

After you have setup SIP, the included scripts will help you to easily run and maintain SIP.

Start

$ bin/start-DEV.sh
$ bin/start-PROD.sh

Stop

$ bin/stop-DEV.sh
$ bin/stop-PROD.sh

Integration Tests

A separate TEST Docker environment will be automatically built if you chose to build either a DEV or PRODUCTION environment during the setup process.

$ bin/test.sh

Database Migrations

SIP uses Flask-Migrate to handle any database schema changes and migrations.

NOTE: This should only be performed for the DEV environment.

Initialize

This should never need to be performed unless you delete the included migrations directory. Additionally, it is only meant to run on the DEV environment.

$ bin/db-init-DEV.sh

Migrate

Once you have made some changes to the database schema in the models.py file, you need to generate the schema migrations. This is also only meant to run on the DEV environment.

$ bin/db-migrate-DEV.sh

Upgrade

After you have created the schema migrations (or have received migrations through a git pull), you need to upgrade your database. This can run on the DEV or PRODUCTION environments.

$ bin/db-upgrade-DEV.sh
$ bin/db-upgrade-PROD.sh

Debugging

If SIP refuses to start, and you suspect the issue is with the Docker container itself, you can enter a shell to the containers:

$ docker exec -i -t sip_web-dev_1 /bin/sh
$ docker exec -i -t <container_name> /bin/sh

Setup

Configuration

Before you run the included setup script, you should review the setup configuration file:

services/web/etc/setup.ini

This file contains a list of initial values that will be added to the database during setup.

The values include:

  • Indicator confidences (first value will be used as the default)

  • Indicator impacts (first value will be used as the default)

  • Indicator statuses (first value will be used as the default)

  • Indicator types

  • Intel sources

Setup Script

The included setup script will walk you through the installation and configuration of SIP:

$ ./setup.py

The setup script will walk you through:

  • Creating dev/test/production Docker environments

  • Setting the MySQL root user password

  • Creating a non-root MySQL user and password

  • Creating an optional self-signed HTTPS certificate

If you choose not to create a self-signed certificate, the script will notify you that you must supply your own certificate and where to place it.

Once you answer the setup script’s questions, it will generate files containing the environment variables for the MySQL and Flask Docker containers. The paths to these files will be shown by the setup script for you to review.

MAKE SURE TO NOTE THE RANDOM ADMIN PASSWORD REPORTED AT THE END BY THE SETUP SCRIPT!

Example

Example output from the setup script is shown below:

Build a DEV environment (y/N)? y
Build a PRODUCTION environment (y/N)? n

MYSQL root password:
Confirm:

MYSQL username: SIP
MYSQL password:
Confirm:

NGINX: Generate a self-signed certificate (y/N)? y

Generating a 2048 bit RSA private key
....................................+++
................+++
writing new private key to '/home/dev/SIP/services/nginx/certs/key.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Somewhere
Locality Name (eg, city) []:Someplace
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Integral Defense
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:sip.local
Email Address []:

Building db-dev
Step 1/3 : FROM mysql:8.0.15
 ---> 81f094a7e4cc
Step 2/3 : ADD create.sql /docker-entrypoint-initdb.d
 ---> Using cache
 ---> e7a82071400a
Step 3/3 : ADD conf.d/ /etc/mysql/conf.d
 ---> Using cache
 ---> 7a89a9af0aef
Successfully built 7a89a9af0aef
Successfully tagged sip_db-dev:latest
Building web-dev
Step 1/8 : FROM python:3.7
 ---> dc6a60638123
Step 2/8 : RUN apt-get update && apt-get install -y mysql-client
 ---> Using cache
 ---> 824a8a8c41b8
Step 3/8 : WORKDIR /usr/src/app
 ---> Using cache
 ---> 31e50c746580
Step 4/8 : COPY ./requirements.txt /usr/src/app/requirements.txt
 ---> Using cache
 ---> bf7180697bde
Step 5/8 : RUN pip install -r requirements.txt
 ---> Using cache
 ---> e5db87e9dfca
Step 6/8 : COPY ./entrypoint-DEV.sh /usr/src/app/entrypoint-DEV.sh
 ---> Using cache
 ---> 18ad61b7f770
Step 7/8 : COPY . /usr/src/app
 ---> 74a7f1ef420e
Step 8/8 : CMD ["/usr/src/app/entrypoint-DEV.sh"]
 ---> Running in 3751f57a9945
Removing intermediate container 3751f57a9945
 ---> adb4c05e4380
Successfully built adb4c05e4380
Successfully tagged sip_web-dev:latest
Building nginx-dev
Step 1/4 : FROM nginx:1.15.6-alpine
 ---> d3dcc25e0dc4
Step 2/4 : RUN rm /etc/nginx/conf.d/default.conf
 ---> Using cache
 ---> 0a7e23e8e331
Step 3/4 : COPY ./server-DEV.conf /etc/nginx/conf.d
 ---> Using cache
 ---> 9711b1acf628
Step 4/4 : ADD certs/ /etc/nginx/certs
 ---> Using cache
 ---> a7d1430078a5
Successfully built a7d1430078a5
Successfully tagged sip_nginx-dev:latest
Building db-test
Step 1/3 : FROM mysql:8.0
 ---> 81f094a7e4cc
Step 2/3 : ADD create.sql /docker-entrypoint-initdb.d
 ---> Using cache
 ---> e7a82071400a
Step 3/3 : ADD conf.d/ /etc/mysql/conf.d
 ---> Using cache
 ---> 7a89a9af0aef
Successfully built 7a89a9af0aef
Successfully tagged sip_db-test:latest
Building web-test
Step 1/8 : FROM python:3.7
 ---> dc6a60638123
Step 2/8 : RUN apt-get update && apt-get install -y mysql-client
 ---> Using cache
 ---> 824a8a8c41b8
Step 3/8 : WORKDIR /usr/src/app
 ---> Using cache
 ---> 31e50c746580
Step 4/8 : COPY ./requirements.txt /usr/src/app/requirements.txt
 ---> Using cache
 ---> bf7180697bde
Step 5/8 : RUN pip install -r requirements.txt
 ---> Using cache
 ---> e5db87e9dfca
Step 6/8 : COPY ./entrypoint-TEST.sh /usr/src/app/entrypoint-TEST.sh
 ---> Using cache
 ---> b8e995a98fb7
Step 7/8 : COPY . /usr/src/app
 ---> 0fe5d3d26f63
Step 8/8 : CMD ["/usr/src/app/entrypoint-TEST.sh"]
 ---> Running in b0d24537eb35
Removing intermediate container b0d24537eb35
 ---> 2fd2f016e9ee
Successfully built 2fd2f016e9ee
Successfully tagged sip_web-test:latest
Building nginx-test
Step 1/4 : FROM nginx:1.15.6-alpine
 ---> d3dcc25e0dc4
Step 2/4 : RUN rm /etc/nginx/conf.d/default.conf
 ---> Using cache
 ---> 0a7e23e8e331
Step 3/4 : COPY ./server-TEST.conf /etc/nginx/conf.d
 ---> Using cache
 ---> aababc77bff6
Step 4/4 : ADD certs/ /etc/nginx/certs
 ---> Using cache
 ---> 19b43be1c9b2
Successfully built 19b43be1c9b2
Successfully tagged sip_nginx-test:latest


===  SUMMARY  ===

MYSQL: Review create.sql: /home/dev/SIP/services/db/create.sql
MYSQL: Review the DEV environment variables: /home/dev/SIP/services/db/docker-DEV.env
MYSQL: Review the TEST environment variables: /home/dev/SIP/services/db/docker-TEST.env

NGINX: Certificate: /home/dev/SIP/services/nginx/certs/cert.pem
NGINX: Certificate key: /home/dev/SIP/services/nginx/certs/key.pem

WEB: Review the DEV environment variables: /home/dev/SIP/services/web/docker-DEV.env
WEB: Review the TEST environment variables: /home/dev/SIP/services/web/docker-TEST.env

===  FINISH DEV SETUP  ===
Creating network "sip_dev" with driver "bridge"
Creating volume "sip_mysql-dev" with local driver
Creating sip_db-dev_1 ...
Creating sip_db-dev_1 ... done
Creating sip_web-dev_1 ...
Creating sip_web-dev_1 ... done
Creating sip_nginx-dev_1 ...
Creating sip_nginx-dev_1 ... done
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Waiting for SIP (DEV) to start...
Stopping sip_nginx-dev_1 ... done
Stopping sip_web-dev_1   ... done
Stopping sip_db-dev_1    ... done
Removing sip_nginx-dev_1 ... done
Removing sip_web-dev_1   ... done
Removing sip_db-dev_1    ... done
Removing network sip_dev
Creating network "sip_dev" with driver "bridge"
Creating sip_db-dev_1 ...
Creating sip_db-dev_1 ... done
Starting sip_db-dev_1 ... done
[2019-03-07 15:53:22,746] INFO in __init__: SIP starting
[2019-03-07 15:53:23,102] INFO in __init__: SIP starting
[2019-03-07 15:53:23,191] INFO in manage: SETUP: Created user role: admin
[2019-03-07 15:53:23,209] INFO in manage: SETUP: Created user role: analyst
[2019-03-07 15:53:23,227] INFO in manage: SETUP: Created indicator confidence: LOW
[2019-03-07 15:53:23,244] INFO in manage: SETUP: Created indicator confidence: MEDIUM
[2019-03-07 15:53:23,262] INFO in manage: SETUP: Created indicator confidence: HIGH
[2019-03-07 15:53:23,280] INFO in manage: SETUP: Created indicator impact: LOW
[2019-03-07 15:53:23,297] INFO in manage: SETUP: Created indicator impact: MEDIUM
[2019-03-07 15:53:23,315] INFO in manage: SETUP: Created indicator impact: HIGH
[2019-03-07 15:53:23,332] INFO in manage: SETUP: Created indicator status: NEW
[2019-03-07 15:53:23,350] INFO in manage: SETUP: Created indicator status: FA
[2019-03-07 15:53:23,368] INFO in manage: SETUP: Created indicator status: IN PROGRESS
[2019-03-07 15:53:23,386] INFO in manage: SETUP: Created indicator status: ANALYZED
[2019-03-07 15:53:23,404] INFO in manage: SETUP: Created indicator status: INFORMATIONAL
[2019-03-07 15:53:23,423] INFO in manage: SETUP: Created indicator status: DEPRECATED
[2019-03-07 15:53:23,440] INFO in manage: SETUP: Created indicator type: Address - ipv4-addr
[2019-03-07 15:53:23,458] INFO in manage: SETUP: Created indicator type: Email - Address
[2019-03-07 15:53:23,476] INFO in manage: SETUP: Created indicator type: Email - Content
[2019-03-07 15:53:23,494] INFO in manage: SETUP: Created indicator type: Email - Subject
[2019-03-07 15:53:23,511] INFO in manage: SETUP: Created indicator type: Hash - MD5
[2019-03-07 15:53:23,529] INFO in manage: SETUP: Created indicator type: Hash - SHA1
[2019-03-07 15:53:23,547] INFO in manage: SETUP: Created indicator type: Hash - SHA256
[2019-03-07 15:53:23,566] INFO in manage: SETUP: Created indicator type: URI - Domain Name
[2019-03-07 15:53:23,584] INFO in manage: SETUP: Created indicator type: URI - Path
[2019-03-07 15:53:23,601] INFO in manage: SETUP: Created indicator type: URI - URL
[2019-03-07 15:53:23,619] INFO in manage: SETUP: Created intel source: OSINT
[2019-03-07 15:53:23,679] INFO in manage: SETUP: Created admin user with password: o@eV5x=oU{W][4T>o?_m