Ostorlab OXO Scanner Orchestrator

2.3.2 verified Sat May 09 auth: no python

Ostorlab (oxo) is a security scanner orchestrator that manages and coordinates scanning agents across various assets (iOS, Android, HarmonyOS, web, network, etc.). It provides a CLI (`oxo scan`) to run, stop, and manage scans via a distributed architecture. The current stable version is 2.3.2, released in May 2025, with active development on GitHub. It requires Python >=3.9.

pip install ostorlab

Common errors

error ModuleNotFoundError: No module named 'ostorlab.cli' ↓

cause Ostorlab may not be installed, or an older version (<1.0) was used where the CLI was structured differently. Also, import path changed after v2.

fix

Upgrade ostorlab: pip install --upgrade ostorlab. If using a virtual environment, ensure it's activated.

error AttributeError: module 'ostorlab' has no attribute 'Agent' ↓

cause Trying to import `Agent` directly from `ostorlab` instead of the correct submodule.

fix

Use from ostorlab.agent import Agent.

Warnings

breaking In version 2.0.0, Python requirement was bumped to >=3.9 (from 3.14 in v2? Actually v2.0.0 release note says 'bump python version to 3.14' – this is likely a typo; the PyPI metadata requires >=3.9). Ensure your Python version is at least 3.9. ↓

fix Use Python 3.9 or later. Run `python --version` to check.

gotcha The `start_scan` function expects the path to an agent group definition YAML file. A common mistake is passing a raw dictionary instead of a file path. This will raise a TypeError. ↓

fix Create a YAML file with the agent group definition and pass the file path as a string to `start_scan`.

Imports

start_scan
wrong
```
import ostorlab.start_scan
```
correct
```
from ostorlab.cli import start_scan
```
start_scan is a function inside the CLI module, not a top-level export.

Agent

wrong

import Agent from ostorlab

correct

from ostorlab.agent import Agent

Agent class is in the agent subpackage.

Quickstart

Initialize and start a scan using an agent group definition YAML and a list of assets. The YAML file defines which agents to run.

from ostorlab.cli import start_scan

# Example: scan a domain (replace with your target)
scan_id = start_scan(
    agent_group_definition='path/to/agent_group.yaml',
    assets=[{'type': 'DomainName', 'name': 'example.com'}],
)
print(f'Scan started with ID: {scan_id}')