Skip to content

Meta risk analysis and scoring system based on open-source fully automated intelligence gathering

License

Notifications You must be signed in to change notification settings

Heretyc/inntinn

Repository files navigation

Inntinn: Intelligence

inntinn

API Documentation: Swagger Code style: black pypi wheel

OSINT composite vulnerability database.

Inntinn - Scotts Gaelic for "Intelligence"

Inntinn has one primary objective: simplify the process of communicating risk to stakeholders and measuring risk over time in a concise manner.

Acknowledging that threat-actors perform reconnaissance and go for “low hanging fruit”, Inntinn aims to model this behavior in order to generate a single number that can be used as a consistent benchmark even among dissimilar organizations.

Scores are based on metrics that more threat-actors are using to date: target company valuation, vulnerabilities they are actually aware of, and vulnerabilities that are most likely to work.

To put it another way: Gross Company Assets, Vulnerability Notoriety, and the damage or ease of use on a vulnerability.

Inntinn Scores

There are 2 forms of scoring, Per Device and Per Organization.

  • The Per Device score is calculated using a list of all CVE’s (vulnerabilities) that a device is vulnerable to, and the company which owns it. (If the company is not publicly traded, the lowest score metric is used to communicate that the organization is not a primary target of attackers globally)
  • The Per Organization score only needs the summation of all organizational Inntinn Per Device scores. This can be used as a “Per Department”, “Per Datacenter” or any other organizational unit including the company as a whole.

Per Device

The “Per Device” score represents the cumulative risk posed by a single device within an organization.

The guiding principles behind this score are:

  1. Rather than using a complex metric, we boil-down the score into a simple 1-100 percentage. (100% = highest risk)

  2. Risk is updated as threats evolve over time. Inntinn pulls directly from the NIST National Vulnerability Database, updating as CVE’s change in scope over time. As a vulnerability grows in notoriety, so does the score.

  3. As new PoCs (Proof of Concept code) are added to the ExploitDB, scores are dynamically adjusted to account for greater likelihood of exploitation.

  4. Finally, scoring is based on public financial fillings with the Securities and Exchange Commission (SEC). Base scores for companies curve sharply upward as we look at the most profitable companies.

Score Distribution

Per Organization

  • A cumulative risk score is calculated by simply adding each Inntinn device score up. Just that simple.

One final note on scores

Device and Org scores will change over time as threats evolve and new information becomes available. While the underlying data sets outlined in the "Per Device" section above will not necessarily change, scores will fluctuate between database updates nonetheless.

Database updates are performed at an interval of your choosing, however we recommend at least once weekly.

Installation and Usage (Technical)

  1. OS X, Linux & Windows:
pip install inntinn
  1. Ensure that a working MongoDB database is accessible and utilize the Example configuration file to enable read/write on the given MongoDB database.

Example Config:

{"inntinn":{"instance":"thedb",
       "user": "audrey",
       "pass": "asdfghjjkl12345",
       "uri": "mongodb://4.2.2.2:27017/"}}
  1. Import Inntinn within your Python code, instance the database, provide it the config file and perform an update to populate the database:
import inntinn
db = inntinn.Database("/path/to/your/config.json")

db.update()
  1. a) Lookup the SEC CIK for your chosen company:
import inntinn
db = inntinn.Database("/path/to/your/config.json")

companies = db.cik_lookup("apple")
for key, value in companies.items():
    print(f"CIK: {key} = {value}")

b) Or if you are feeling lucky, just use the company name:

import inntinn
db = inntinn.Database("/path/to/your/config.json")

device_score = db.score_device_list_fuzzy(["CVE-2019-0708", "CVE-1999-0019", "CVE-2018-0840", "CVE-2021-22721", "CVE-2021-3619"], "Apple Inc")
  1. If you didn't opt for option "b" above, you may now perform scoring:
import inntinn
db = inntinn.Database("/path/to/your/config.json")

device_score = db.score_device_list(["CVE-2019-0708", "CVE-1999-0019", "CVE-2018-0840", "CVE-2021-22721", "CVE-2021-3619"], 320193)
  1. After performing scoring on a Per Device level for each device in the org, you may calculate the Per Org score:
import inntinn
db = inntinn.Database("/path/to/your/config.json")

device_a_score = db.score_device_list(["CVE-2019-0708", "CVE-1999-0019", "CVE-2018-0840", "CVE-2021-22721", "CVE-2021-3619"], 320193)
# any number of device calculations here
device_z_score = db.score_device_list(["CVE-2021-2336", "CVE-2021-2390", "CVE-2018-0840", "CVE-2019-0708"], 320193)
org_score = db.score_org([device_a_score, device_z_score])

API

Optionally, Inntinn has an accompanying Sanic based API which does not require a proxy like most Python frameworks. To view the documentation for the API visit bhax.net/api

API Documentation: Swagger

Additionally, once the API is running, you can visit:

https ://your_host/swagger

for a dynamically updated Swagger spec page that is accessible even without internet access.

The API is functional and fast, but we do not recommend running it on Windows as multi-threading is not available at this time. Running on Windows will result in dramatically slower response processing.

Getting started

The API itself is located under inntinn/api.py and must be launched with appropriate permissions to open sockets on Port 80 & Port 443.

Use the example_config.json and be pay close attention to the "inntinn_api" section. Generate your certs and set the config to point to the files.

Important Note: Currently, the config.json must be called "config.json" and placed in the same directory as the api.py application. (This behavior is likely to change in a future update allowing one to pass the config as a command line argument at launch)

Authentication

The database is read-only in all cases but one, database updates. For this reason, all endpoints do not require authentication of any kind... except the /server endpoint.

Authentication is done using JWTs (JSON Web Tokens) which are RFC 7519 compliant.

Example

For the admin user defined in the config.json, the default password is "change_me" the following example shows how to authenticate with JWTs to update the server:

import requests
server_uri = "https://127.0.0.1"

# Obtain a JWT
payload = {"username": "admin", "password": "change_me"}
auth_response = requests.post(f"{server_uri}/auth", json=payload, verify=False)
auth_response_json = auth_response.json()

# Now use the JWT
response = requests.post(
    f"{server_uri}/server",
    json=payload,
    headers={"Authorization": f"Bearer {auth_response_json['access_token']}"},
    verify=False,
)

Meta

Brandon Blackburn – PGP Encrypted Chat @ Keybase

Distributed under the Apache 2.0 license. See LICENSE for more information.

TL;DR: For a human-readable & fast explanation of the Apache 2.0 license visit: http://www.tldrlegal.com/l/apache2

https://github.com/BlackburnHax/inntinn