Whitelist

To create, modify, delete, or retrieve import whitelist entries from the ThreatStream platform.

Request

/api/v1/orgwhitelist/

HTTP Methods:

Create a new whitelist entry POST /api/v1/orgwhitelist/
Get a list of whitelist entries GET /api/v1/orgwhitelist/
Modify contextual notes associated with existing whitelist entries PATCH /api/v1/orgwhitelist/
Delete a whitelist entry DELETE /api/v1/orgwhitelist/

Attributes: See the table below

Request Attributes

Attribute Definition
file Path to the CSV file containing the whitelist entries you want to add.
format

Format of whitelist exports.

Specify csv or json
limit

The limit variable controls the number of results returned every time an API call is made; the total number of results may be much larger than returned in one API call.

If limit is not specified, 10 results are returned with each API call. Specifying limit=0 will return up to a maximum of 1000 results (if available).

remove_existing

Whether you want to replace existing whitelist entries with the entries specified in the request.

true—remove existing whitelist entries and replace with specified entries.

false—do not remove existing whitelist entries.

Default:false

showNote

Whether contextual notes are included in the response.

true—notes are included.

false—notes are not included.

Default:true

whitelist

Whitelist entries can be specified in a list, as in the following example:

{"whitelist": [{value_type: "domain", value: "example.com", notes: "example domain"}]}

Whitelist Attributes

  • value_type—cidr, domain, email, ip, md5 url, user-agent
  • value—value of the entry you want to add
  • notes—contextual note associated with the entry

You can also specify whitelist entries in a CSV file.

The CSV file must adhere to the following requirements:

  • The entries must be contained in a valid CSV file with the following header line: value_type,value,notes.
  • value_type must be specified for each entry. Possible types include domain, email, ip, md5, url, user-agent, and cidr.
  • value must be specified for each entry. Values must be valid entries based on the specified type. For example, if you specify ip for type, the corresponding value must be a valid IP address.
  • notes is optional for each entry.
  • All text in the CSV file must be lower-cased.

The following is an example of a valid CSV file:

value_type,value,notes
domain,*wildcard-example.com,this is a valid domain
email,account@example.com,example note
ip,1.2.3.4,
md5,fe01ce2a7fbac8fafaed7c982a04e229,
url,http://example.com,
user-agent,myagent1,
cidr,192.0.2.0/24,

Response

Format: JSON

Attributes: See the table below

Response Attributes

Attribute Definition
created_ts Timestamp of when the entry was created.
id Unique ID associated with the whitelist entry.
modified_ts Timestamp of when the entry was most recently modified.
notes Contextual note associated with the entry
value Value of the entry.
value_type Type of entry—cidr, domain, email, ip, md5 url, user-agent

Examples

  1. To return a list of your 10 most recently added whitelist entries:

    Copy 
    curl -X GET 'https://api.threatstream.com/api/v1/orgwhitelist/?format=json'  -H 'Content-Type:application/json' -H 'Authorization: apikey <username>:<api_key>'

  2. To add an entry to your import whitelist:

    Copy 
    curl -X POST 'https://api.threatstream.com/api/v1/orgwhitelist/bulk/' -d '{"whitelist":[{"value_type": "domain", "value": "example44.org", "notes": "example domain"}]}' -H 'Content-Type:application/json' -H 'Authorization: apikey <username>:<api_key>'

  3. To add entries to your import whitelist from a CSV file:

    Copy 
    curl -X POST 'https://api.threatstream.com/api/v1/orgwhitelist/upload/?remove_existing=false'  -F "file=@whitelist.csv" -H 'Authorization: apikey <username>:<api_key>'

    where the whitelist.csv file contains the following data:

    value_type,value,notes
domain,*foo.wildcarddomain.com,some notes on foo
domain,*wildcarddomain.com,
email,test@email.com,
ip,8.8.8.8,notes on ip address
md5,fe01ce2a7fbac8fafaed7c982a04e229,this is a test md5 hash
url,http://gooddomain.com/,

  4. To replace your existing import whitelist with entries from a CSV file:

    Copy 
    curl -X POST 'https://api.threatstream.com/api/v1/orgwhitelist/upload/?remove_existing=true'  -F "file=@whitelist.csv" -H 'Authorization: apikey <username>:<api_key>'

  5. To export your import whitelist in CSV format:

    Copy 
    curl -X GET 'https://api.threatstream.com/api/v1/orgwhitelist/?showNote=True&format=csv'  -H "Content-Type:application/json" -H 'Authorization: apikey <username>:<api_key>'

  6. To export your import whitelist in JSON format:

    Copy 
    curl -X GET 'https://api.threatstream.com/api/v1/orgwhitelist/?showNote=True&format=json'  -H "Content-Type:application/json" -H 'Authorization: apikey <username>:<api_key>'

  7. To remove an entry from your import whitelist:

    Copy 
    curl -X DELETE 'https://api.threatstream.com/api/v1/orgwhitelist/<Entry_ID>/' -H 'Authorization: apikey <username>:<api_key>'

    where <Entry_ID> is the ID associated with the whitelist entry you want to delete. To determine the entry ID, execute return a list of your current whitelist entries and note the ID value associated with the entry of interest.

  8. To edit the note associated with an import whitelist entry:

    Copy 
    curl -X PATCH 'https://api.threatstream.com/api/v1/orgwhitelist/<Entry_ID>/' -d '{"notes":"updated note text"}' -H "Content-Type:application/json" -H 'Authorization: apikey <username>:<api_key>'

    where <Entry_ID> is the ID associated with the whitelist entry you want to modify. To determine the entry ID, return a list of your current whitelist entries and note the ID value associated with the entry of interest.