This project is dedicated to automate the detection of known exploited vulnerabilities through a single command, it includes exploits for vulnerabilities from:

• Known Exploited Vulnerabilities Catalog by CISA
• Tsunami by Google
• Agent Asteroid by Ostorlab
• Bug Bounty Programs

Python 3.9 or greater is required to install KEV via pip.

Docker is required to run scans locally. To install docker, please follow these instructions.

Ostorlab ships as a Python package on pypi. To install it, simply run the following command if you have pip already installed.

pip install -U ostorlab

This repo is an Agent Group Definition of the open-source ostorlab scanner. An agent group is nothing but a config file that defines the list of components to run during the scan.

For a full tutorial on how to use Ostorlab CLI, check the following tutorial.

By default, Ostorlab KEV agent group agent_group.yaml uses the following agents:

• Agent Nuclei
• Agent Tsunami
• Agent Nmap
• Agent Asteroid
• Agent Metasploit

To perform your first scan, you have several options depending on your target.

Here's how you can get started:

To scan an IP address, simply run the following command:

ostorlab scan run --install -g agent_group.yaml ip 8.8.8.8

And you can scan more than one IP address by specifying them, separated by spaces:

ostorlab scan run --install -g agent_group.yaml ip 8.8.8.8 1.1.1.1 4.4.4.0/24

To scan a domain, simply run the following command:

ostorlab scan run --install -g agent_group.yaml domain-name www.example.com

This command will download and install the required agents specified in the YAML file and perform the scan on the domain www.example.com.

To scan a link, simply run the following command:

ostorlab scan run --install -g agent_group.yaml link --url https://www.example.com --method GET

This command will download and install the required agents specified in the YAML file and perform the scan on the link https://www.example.com using the specified method.

To improve the scope of detection, it's possible to enumerate and target subdomains of a given asset by adding subfinder and/or dnsx to the agent group definition agent_group.yaml.

agent:
  ...
  - key: agent/ostorlab/subfinder
  - key: agent/ostorlab/dnsx
  ...

And then run it on the domain you would like to target:

ostorlab scan run --install -g agent_group.yaml domain-name example.com

To run oxo in a container, you may use the publically available image and run the following command:

docker run -v /var/run/docker.sock:/var/run/docker.sock -v ./agent_group.yaml:/agent_group.yaml  ostorlab/oxo:latest scan run --install -g /agent_group.yaml link --url https://www.example.com --method GET

Notes:

• The command starts directly with: scan run, this is because the ostorlab/oxo image has oxo as an entrypoint.
• It is important to mount the docker socket so oxo can create the agent in the host machine.

To see the scan progress, use the scan list command:

ostorlab scan list

List findings in a particular scan:

ostorlab vulnz list -s <scan-id>

To list the details of a vulnerability:

ostorlab vulnz describe -v <vuln-id>

For the moment, we are currently focused on the CISA KEV Database and Google Tsunami.