About

Cymon is the largest tracker and aggregator of security reports. It ingests events about malware, botnets, phishing, spam and other malicious activities from almost 200 sources daily. On average, more than 15,000 unique IPs and 50,000 events are processed each day.

Cymon API v2.0 is coming soon!

Authentication

Cymon allows anonymous API requests, but they will be rate-limited. You will need to authenticate if you want higher access rates.

Authenticated request made to the Cymon API needs to include your access key in the Authorization HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings. For example:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Unauthenticated responses that are denied permission will result in an HTTP 401 Unauthorized response with an appropriate WWW-Authenticate header. For example:

WWW-Authenticate: Token

The curl command line tool may be useful for testing token authenticated APIs. For example:

curl -X GET https://cymon.io/api/nexus/v1/blacklist/ip/malware/ -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'

You can register for an API key here

HTTP Status Codes

Code Description
200 Ok Success
401 Unauthorized: Access is denied due to invalid token.
404 Not Found: The request was invalid or cannot be otherwise served.
429 Too Many Requests: Rate limit exceeded.
500 API Error

Example Error Response:

HTTP 404 Not Found
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS

{
    "detail": "Not found."
}

Rate Limits

Connection Type Rate
Anonymous User 500/day
Authenticated User 1000/day

To request for a limit increase, please contact info@cymon.io

Example Rate Limit Error:

HTTP 429
Retry-After: 86397
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS

{
    "detail": "Request was throttled. Expected available in 86397.0 seconds."
}

APIs

You can interact and test the APIs in your browser:

https://cymon.io/api/docs/

IP Lookup

Provides IP object details

GET /api/nexus/v1/ip/{addr}/

Parameters

Parameter Parameter Type Data Type Required Description
addr path string Yes IP address

Sample response body

{
    "addr": "5.248.253.190",
    "created": "2015-06-19T22:11:26",
    "updated": "2015-06-19T22:11:43",
    "sources": [
        "pbl.spamhaus.org",
        "zen.spamhaus.org",
        "v6.fullbogons.cymru.com",
        "tor.ahbl.org",
        "dnsbl.ahbl.org",
        "virustotal.com",
        "urlquery.net"
    ],
    "events": "https://cymon.io/api/nexus/v1/ip/5.248.253.190/events",
    "domains": "https://cymon.io/api/nexus/v1/ip/5.248.253.190/domains",
    "urls": "https://cymon.io/api/nexus/v1/ip/5.248.253.190/urls"
}

HTTP Status Codes

Status Code Reason
200 IP found in database
404 IP not found
429 Request throttled

IP Events

Provides security event resources

GET /api/nexus/v1/ip/{addr}/events/

Parameters

Parameter Parameter Type Data Type Required Description
addr path string Yes IP address

Sample response body

{
    "count": 7,
    "next": null,
    "previous": null,
    "results": [
        {
            "title": "IP blacklisted by zen.spamhaus.org",
            "description": null,
            "details_url": null,
            "created": "2015-06-19T22:11:29",
            "updated": "2015-06-19T22:11:29",
            "tag": "dnsbl"
        },
        {
            "title": "Malware reported by VirusTotal.com",
            "description": "Scan date: 2015-06-19 05:35:57\nVirusTotal score: 4/63\nDomain: 5.248.253.190\nMalware URL: hxxp://5.248.253.190/pod1/mobile7.exe\n",
            "details_url": "https://www.virustotal.com/en/ip-address/5.248.253.190/information/",
            "created": "2015-06-19T05:35:57",
            "updated": "2015-06-19T22:11:43",
            "tag": "malware"
        },
        ...
    ]
}

HTTP Status Codes

Status Code Reason
200 IP found in database
404 IP not found
429 Request throttled

IP Domains

Provides domains associated with an IP

GET /api/nexus/v1/ip/{addr}/domains/

Parameters

Parameter Parameter Type Data Type Required Description
addr path string Yes IP address

Sample response body

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "shower-radio.com",
      "created": "2015-10-19T16:22:58Z",
      "updated": "2015-10-20T16:23:22Z"
    }
  ]
}

HTTP Status Codes

Status Code Reason
200 IP found in database
404 IP not found
429 Request throttled

IP URLs

Provides URLs associated with an IP

GET /api/nexus/v1/ip/{addr}/urls/

Parameters

Parameter Parameter Type Data Type Required Description
addr path string Yes IP address

Sample response body

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "location": "http://alfaqui.com/~buzon/21/09.exe",
      "created": "2015-09-07T18:29:57Z",
      "updated": "2015-09-07T18:29:57Z"
    }
  ]
}

HTTP Status Codes

Status Code Reason
200 IP found in database
404 IP not found
429 Request throttled

IP Blacklist

Retrieve list of IPs that are associated with certain tag

GET /api/nexus/v1/blacklist/ip/{tag}/

Parameters

Parameter Parameter Type Data Type Required Description
tag path string Yes One of the following tags:
  • malware
  • botnet
  • spam
  • phishing
  • malicious activity
  • blacklist
  • dnsbl
days query integer No Use data collected since 1-3 days ago (default is 1)

Sample response body

{
    "count": 617,
    "next": "https://cymon.io/api/nexus/v1/blacklist/ip/malware/?days=1&offset=10",
    "previous": null,
    "results": [
        {
            "addr": "42.115.158.45",
            "url": "https://cymon.io/api/nexus/v1/ip/42.115.158.45"
        },
        {
            "addr": "182.16.233.188",
            "url": "https://cymon.io/api/nexus/v1/ip/182.16.233.188"
        },
        ...
    ]
}

Domain Lookup

Provides domain object detail

GET /api/nexus/v1/domain/{name}

Parameters

Parameter Parameter Type Data Type Required Description
name path string Yes Domain name

Sample response body

{
    "name": "hiepkute1970.zapto.org",
    "created": "2015-07-07T14:14:11",
    "updated": "2015-07-07T14:14:11",
    "sources": [
        "malwr.com"
    ],
    "ips": [
        "https://cymon.io/api/nexus/v1/ip/42.115.158.45"
    ],
    "urls": []
}

Domain Blacklist

Retrieve list of domains that are associated with certain tag

GET /api/nexus/v1/blacklist/domain/{tag}/

Parameters

Parameter Parameter Type Data Type Required Description
tag path string Yes One of the following tags:
  • malware
  • botnet
  • spam
  • phishing
  • malicious activity
  • blacklist
  • dnsbl
days query integer No Use data collected since 1-3 days ago (default is 1)

Sample response body

{
    "count": 617,
    "next": "https://cymon.io/api/nexus/v1/blacklist/domain/malware/?offset=10",
    "previous": null,
    "results": [
        {
            "name": "advertblocks.vitr.alawar.com",
            "url": "https://cymon.io/api/nexus/v1/domain/advertblocks.vitr.alawar.com"
        },
        {
            "name": "vitr.alawar.ru",
            "url": "https://cymon.io/api/nexus/v1/domain/vitr.alawar.ru"
        },
        ...
    ]
}

URL Lookup

Provides security events resource

GET /api/nexus/v1/url/{location}

Parameters

Parameter Parameter Type Data Type Required Description
location path string Yes Escaped URL string

Note that URL string must be url-encoded.

Sample response body

{
    "location": "hxxp://faker.su/data/entry/steam/Steam.exe",
    "created": "2015-04-22T13:33:27.643167Z",
    "updated": "2015-04-22T13:33:27.662668Z",
    "sources": [
        "vxvault"
    ],
    "ips": [
        "https://cymon.io/api/nexus/v1/ip/94.75.240.108"
    ],
    "domain": "https://cymon.io/api/nexus/v1/domain/faker.su"
}

Testing with CURL

curl 'https://cymon.io/api/nexus/v1/url/http%253A%252F%252Ffaker.su%252Fdata%252Fentry%252Fsteam%252FSteam.exe'

HTTP Status Codes

Status Code Reason
200 URL found in database
404 URL not found
429 Request throttled

Pagination

Cymon API uses "Limit-Offset" pagination. The client includes both a "limit" and an "offset" query parameter. The limit indicates the maximum number of items to return. The default limit size is 10. The offset indicates the starting position of the query in relation to the complete set of unpaginated items.

Request example:

GET https://cymon.io/api/nexus/v1/ip/x.x.x.x/events/?limit=100&offset=400

Response:

{
    "count": 1023,
    "next": "https://cymon.io/api/nexus/v1/ip/x.x.x.x/events/?limit=100&offset=500",
    "previous": "https://cymon.io/api/nexus/v1/ip/x.x.x.x/events/?limit=100&offset=300",
    "results": [
        ...
    ]
}