This repository has been archived on 2022-08-01. You can view files and clone it, but cannot push or open issues or pull requests.
Threat-Intelligence-Service/README.md

131 lines
4.5 KiB
Markdown
Raw Normal View History

2021-04-02 10:10:12 +00:00
# Threat Intelligence Service
A tool for collecting threat intelligence data and running Monte Carlo simulations
based on it.
## Table of Contents
* [Tech Stack](#tech-stack)
* [Features](#features)
* [Installation](#installation)
* [Configuration Setup](#configuration-setup)
* [Usage](#usage)
* [Testing](#testing)
* [Code Formatting](#code-formatting)
* [Documentation](#documentation)
* [Acknowledgments](#acknowledgements)
* [License](#license)
* [Contact Information](#contact-information)
## Technology Stack
The risk calculation scripts are written in [Python][python], along with
prototypes written in [R][r].
The Neo4j graph database uses the [Cypher][cypher] query language.
| Technology | Description | Link |
|------------|----------------------------------|------|
| Neo4j | Graph database management system | [Link](https://neo4j.com/) |
## Features
This repo. provides:
- Scripts for (re)generating incident number and average cost distributions
and running Monte Carlo simulations using those distributions;
- a set of Cypher commands to allow for easy initial population of a Neo4j
threat intelligence graph database with data derived from the
[_Cyber Security Breaches Survey_ 2020][csbs2020]; and
- a full suite of automated linting functions to ensure codebase standardisation.
## Installation
### Threat Intelligence Database (Neo4j)
1. Install [Neo4j Desktop][neo4j-desktop];
1. in the Neo4j Desktop app, create a new Project;
1. in that project, add either a Local DBMS or a Remote Connection (depending
on which environment you are in) and call it Threat Intelligence:
- make sure to update the connection details in `src/scripts/graph.py`.
1. add the file `contrib/database.cypher` to the Project;
1. open your server in the Neo4j Browser;
1. go to the Project Files tab and press the run button next to `database.cypher`.
### Scripts
1. Clone the repo. to your dev. environment (`git clone git@github.com:Rumperuu/Threat-Intelligence-Service.git`);
1. enter the new folder (`cd Threat-Intelligence-Service`);
1. create a virtual Python environment (`python3.⟨version⟩ -m venv pyvenv`);
1. activate your virtual environment (`source ./pyvenv/bin/activate`); and
1. install Python package with pip (`pip install -r requirements.txt`).
## Configuration Setup
TODO: Add environment config.
## Usage
Run `python src/montecarlo.py` to run a Monte Carlo simulation. Use `-h` to view
the available options.
Run `python src/regenerate-distributions.py` to (re)generate all propability
distributions. Use `-h` to view the available options.
## Testing
There are not currently any tests.
## Code formatting
There is not currently any automated code formatting or linting.
### Python Code
Python code must conform to [PEP 8][pep8].
- Run `black --target-version=py38 */**/*.py` to format all Python files with [Black][black].
- Use `--check` to view the output without automatically fixing warnings and
errors.
- Run `pylint */**/*.py --output-format=colorized` to lint all Python files with [Pylint][pylint].
- Pylint does not have the ability to automatically fix warnings and errors.
Pylint configuration settings are found in `.pylintrc`.
## Documentation
There is currently no documentation.
## Acknowledgements
This project was initially developed as part of [KTP № 11598][ktp], with
funding provided by [Innovate UK][innovate-uk] & [Mitigate Cyber][mitigate].
This game was inspired by Hubbard & Seiersen's book _How to Measure Anything in Cybersecurity Risk_.
## License
This project is currently released under the [CRAPL][crapl]. It should **NOT**
be used in a production environment in its current state.
## Contact Information
| Name | Link(s) |
|---------------|-----------------------|
|Ben Goldsworthy| [Email][bgoldsworthy] |
[python]: https://www.python.org/
[r]: https://www.r-project.org/
[cypher]: https://neo4j.com/developer/cypher/
[csbs2020]: https://www.gov.uk/government/statistics/cyber-security-breaches-survey-2020
[neo4j-desktop]: https://neo4j.com/download/?ref=try-neo4j-lp
[pep8]: https://www.python.org/dev/peps/pep-0008/
[black]: https://pypi.org/project/black/
[pylint]: https://pylint.org/
[ktp]: https://info.ktponline.org.uk/action/details/partnership.aspx?id=11598
[innovate-uk]: https://www.gov.uk/government/organisations/innovate-uk
[mitigate]: http://mitigatecyber.com/
[crapl]: https://matt.might.net/articles/crapl/
[bgoldsworthy]: mailto:me+threatintelservice@bengoldsworthy.net