diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 99 |
1 files changed, 0 insertions, 99 deletions
diff --git a/README.md b/README.md deleted file mode 100644 index c2f1325..0000000 --- a/README.md +++ /dev/null @@ -1,99 +0,0 @@ -# soc_collector -- Gathering vulnerability information and presenting it - -## The oneliner - -The collector answers the fundamental question constantly posed by all -SOC staff ever: Can we have lunch now? - -## The elevator pitch - -You're working as a Security Operations Center engineer and your job -is to, one, know when any part of your infrastructure is vulnerable -and, two, if it is, do something smart about it. - -The collector compiles data from vulnerability scanners and stores the -data in a database. You query the collector for the current -vulnerability status of your network infrastructure. - -Without a summary of your vulnerability status and the ability to quickly -deepen your knowledge of a given system, your chances of ever eating -lunch with a clear conscience are slim. - -## The user interface - -TODO - -## The gory^Wtechnical details - -TODO - -## The name - -The "soc" part means Security Operations Center. - -The "collector" part is correct but misleading since `soc_collector` -also processes and presents. - -## The license - -This code is licensed under the 2-Clause BSD License, see LICENSE for -the full text. - -## How to test it out - -The collector has been tested on Debian 11 (Bullseye). Other Unix -systems should also be capable of running a collector. - -Clone the repository. - - git clone https://git.sunet.se/soc_collector.git - -Install dependencies (Debian). - - sudo apt install docker.io docker-compose jq curl apache2-utils - -Start the collector and JWT server, and generate certificates for JWT signing: - - ./quickstart.sh - -Now the database and the API server should be running, now we can try -adding some observations. First, get a JWT for the default user `usr`: - - JWT=$(curl http://localhost:8000/api/v1.0/auth -X POST -p -u usr:pwd | jq -r .access_token) - -Then we use the JWT to add an observation (defined in `example_data.json`): - - curl -s --data-binary @example_data.json -H "Authorization: Bearer $JWT" https://localhost:1443/sc/v0/add - -Try retreiving all observations permitted by our JWT: - - curl -s -H "Authorization: Bearer $JWT" https://localhost:1443/sc/v0/get | json_pp -json_opt utf8,pretty - -We might also filter the data: - - curl -s -H "Authorization: Bearer $JWT" https://localhost:1443/sc/v0/get?port=111 | json_pp -json_opt utf8,pretty - -Believe it or not, but we can also get a single observation by looking up its key (_id): - - curl -s -H "Authorization: Bearer $JWT" https://localhost:1443/sc/v0/get/1633633714355 | json_pp -json_opt utf8,pretty - -We can also limit the number of results and skip N results forward with the parameters limit and skip: - - curl -s -H "Authorization: Bearer $JWT" 'https://localhost:1443/sc/v0/get?limit=5&skip=2' | json_pp -json_opt utf8,pretty - -## Tips and tricks - -There is a convenience script `do-as` which simplifies performing actions as a particular user. - -You can decode a JWT using jq by piping to `jq -r '.access_token | split(".") | .[0],.[1] | @base64d' | jq`. Full example: - - curl http://localhost:8000/api/v1.0/auth -X POST -p -u user1:pwd | jq -r '.access_token | split(".") | .[0],.[1] | @base64d' | jq - -## Development - -There are two docker-compose files used for development: - -- `docker/docker-compose-dev.yaml` for the collector, and -- `auth-server-poc/docker-compose.yml` for the JWT server. - -To apply changes, `source env-vars.sh` and do e.g. `docker-compose -f docker/docker-compose-dev.yaml up -d --build collector`. |