OXO: Building a Message-Driven Security Orchestrator That Chains Docker-Wrapped Scanners
Hook
Most security pipelines are brittle shell scripts that break when tools change output formats. OXO flips this model: wrap each tool in a Docker container that works cohesively with other agents, eliminating the need for custom integration scripts between scanning tools.
Context
Security scanning at scale has always been a coordination nightmare. You need Nmap for network discovery, Nuclei for vulnerability detection, Tsunami for exploitation checks, and dozens of other specialized tools. Traditionally, you’d write custom scripts to parse each tool’s output format, feed data between stages, handle failures, and aggregate results. When a tool updates its JSON schema, your pipeline breaks. When you want to add a new scanner, you rewrite integration code.
OXO takes a different approach by packaging security tools as containerized agents that work together cohesively. According to the README, it’s “built for modularity, scalability and simplicity” and “combines specialized tools to work cohesively to find vulnerabilities and perform actions like recon, enumeration, fingerprinting.” Rather than writing glue code between tools, you can compose scanning workflows by listing agents that should run together.
Technical Insight
The architecture centers on agents distributed as Docker containers. The OXO engine runs locally using your Docker socket, pulling agents from a public store that includes network scanning tools like Nmap, vulnerability scanners like Nuclei and Tsunami, web fingerprinting tools like Whatweb and Wappalyzer, DNS tools like Subfinder and Dnsx, and malware scanning integration with services like Virustotal.
Here’s what a basic scan invocation looks like:
oxo scan run --install \
--agent nmap \
--agent tsunami \
--agent nuclei \
ip 8.8.8.8Or with full agent paths:
oxo scan run --install \
--agent agent/ostorlab/nmap \
--agent agent/ostorlab/tsunami \
--agent agent/ostorlab/nuclei \
ip 8.8.8.8This downloads and installs the specified agents as Docker images and scans the target IP. The agents appear to coordinate automatically, though the README doesn’t detail the internal message-passing mechanism. Based on the modular design, agents likely communicate through a standardized protocol that allows them to work cohesively without explicit wiring.
To build a custom agent, the README indicates you should:
- Clone a template agent repository with setup files
- Modify the agent implementation file to add your scanning logic
- Update the Dockerfile for any extra dependencies
- Configure the
ostorlab.yamlfile with selectors, documentation, image, and license information - Publish to the store
The README mentions that agents use “selectors” defined in ostorlab.yaml but doesn’t provide detailed examples of the manifest structure or the agent API. The store handles agent distribution and automatically builds Docker images from Git repositories when you push release tags.
OXO supports multiple asset types beyond IP addresses:
| Asset | Description |
|---|---|
| agent | Run scan for agent (meta-scanning) |
| ip | Run scan for IP address or IP range |
| link | Run scan for web link with URL, method, headers and request body |
| file | Run scan for a generic file |
| android-aab | Run scan for Android .AAB package |
| android-apk | Run scan for Android .APK package |
| ios-ipa | Run scan for iOS .IPA file |
| domain-name | Run scan for domain name without protocol or port specification |
Results are queryable through the CLI:
oxo scan list # Show all scans
oxo vulnz list --scan-id <scan-id> # List findings
oxo vulnz describe --vuln-id <vuln-id> # Detailed vulnerability reportThe Docker-first design provides isolation and reproducibility. You can run OXO itself in a container for CI/CD integration:
docker run -v /var/run/docker.sock:/var/run/docker.sock \
ostorlab/oxo:latest \
scan run --install --agent nmap --agent nuclei ip 8.8.8.8Note that the command starts with scan run because the ostorlab/oxo image has oxo as its entrypoint. Mounting the Docker socket is required so OXO can create agent containers on the host machine.
Gotcha
The Docker dependency cuts both ways. While containerization provides isolation and reproducibility, it requires Docker socket access, which many security-hardened environments restrict. The README doesn’t document native Kubernetes integration or distributed scanning capabilities, so scaling appears limited to what a single Docker engine can handle. Running OXO inside container orchestrators that don’t expose the Docker socket would require Docker-in-Docker configurations.
Agent discovery and composition aren’t immediately intuitive. The store shows available agents, but understanding how agents work together requires reading individual agent documentation. The README doesn’t explain the coordination mechanism in detail—you see that you can list multiple agents in one command, but the internal message flow or selector system isn’t documented with examples. Learning effective agent combinations comes from experimentation and documentation review rather than guided workflows. The package name discrepancy (install with pip install ostorlab but run with oxo command) may also cause initial confusion.
Verdict
Use OXO if you’re building reusable security pipelines that need to compose multiple tools without writing integration code, if you want to share internal scanners across teams through a marketplace model, or if you’re tired of maintaining brittle shell scripts. It shines for security teams running comprehensive assessments across diverse asset types—mobile apps, infrastructure, web applications—from a unified workflow. The agent model appears designed to make it straightforward to wrap proprietary tools and distribute them. Skip OXO if you’re running single-tool scans where direct invocation is simpler, if your environment can’t accommodate Docker socket mounting, or if you need documented cloud-native distributed scanning at massive scale. For simple vulnerability aggregation from tools you run separately, DefectDojo offers better centralized management without orchestration overhead.
