## https://sploitus.com/exploit?id=F61E01B7-8693-58E3-99BD-4BD871C51A9C
# OASAS - Offensive Automation & Scope-Aware Suite
### Very powerfull tool for agentic pentest and offensive security
---
---
**A single-package pentest / CTF toolkit** — recon, payload templating,
CVE→PoC exploit intelligence, and a provider-agnostic AI layer, with every
network action gated by a written authorization file.
Run it as an interactive shell (`python -m exploit_builder`) or as one-shot
subcommands. The AI backend is your choice: local Ollama, any OpenAI-compatible
server, or Anthropic.
```text
┌ OASAS · at a glance ─────────────────────────────────────────────┐
│ recon portscan · services · fingerprint · dirscan · dns │
│ vuln intel NVD CVE -> reference links · CWE · public PoCs │
│ exploit reverse shells · msfvenom · reverse-shell listener │
│ ai analyze · poc · chat · autonomous scope-gated agent │
│ workspace SQLite — hosts / findings / loot / notes persist │
│ safety every network action gated by config/scope.yaml │
└──────────────────────────────────────────────────────────────────┘
```
## Contents
1. [The one rule everything hangs off](#the-one-rule-everything-hangs-off)
2. [Setup](#setup)
3. [Engagement flow](#engagement-flow)
4. [Choosing an LLM backend](#choosing-an-llm-backend)
5. [Command reference](#command-reference)
6. [Exploit intelligence pipeline](#exploit-intelligence-pipeline)
7. [Rules of Engagement](#rules-of-engagement)
8. [One-shot commands](#one-shot-commands)
9. [Project layout](#project-layout)
10. [Testing](#testing)
11. [Extending it](#extending-it)
12. [Responsible use](#responsible-use)
---
## The one rule everything hangs off
Nothing that touches a network target runs unless that target is written down
first. `config/scope.yaml` is your authorization record; `ScopeGuard` is the
single choke point every caller passes through — the shell, the one-shot CLI,
and the AI agent's own tool calls alike. An out-of-scope request comes back as
an error, never a silent bypass.
```mermaid
flowchart TB
A["OASAS shell (REPL)"] --> G
B["one-shot CLI (click)"] --> G
C["AI agent tool-loop"] --> G
G{"ScopeGuard.check()scope.yaml + Rules of Engagement"}
G -->|not in scope| X["OutOfScopeErrorexit 1 / tool error to the model"]
G -->|authorized| R["recon/*"]
G -->|authorized| V["vuln/*"]
G -->|authorized| E["exploit/*"]
R --> W[("workspace — SQLite")]
V --> W
E --> W
```
Payload *generation* (reverse shells, web-test markers, cyclic patterns, PoC
drafting) has no network side effects at all — it only produces text/code for
you to use in your own tooling, so it sits outside the gate.
---
## Setup
```bash
pip install -r requirements.txt
cp config/scope.yaml.example config/scope.yaml # edit: your authorized targets
cp config/llm.yaml.example config/llm.yaml # optional: pick an LLM backend
```
`config/scope.yaml` ships authorizing only `127.0.0.1`, `localhost`, and a
sample lab CIDR. Edit it before running any active module.
---
## Engagement flow
A run walks through six stages. Recon, analysis, and exploitation all persist
into one SQLite workspace; `export` reads back whatever has accumulated there,
so you don't have to run every stage, or run them in order, for the report to be
complete.
```mermaid
flowchart LR
A["authorizescope.yaml"] --> B["connectLLM backend"]
B --> C["reconportscan / services"]
C --> D["analyzecve / exploit-suggest / AI findings"]
D --> E["exploitfetch / shell / listen"]
E --> F["exportmd · json · html · pdf"]
C -. writes .-> W[("workspace")]
D -. writes .-> W
E -. writes .-> W
W -. read .-> F
```
```
$ python -m exploit_builder # animated intro + REPL
oasas> targets # what scope.yaml authorizes
oasas> connect ollama llama3.1 # wire up a local agent, no API key
oasas> workspace new lab # named, persistent engagement
oasas> recon 192.168.56.10 analyze # scan + AI analysis
oasas> exploit-suggest 192.168.56.10 # services -> CVEs + links + public PoCs
oasas> export html # report from everything recorded
```
---
## Choosing an LLM backend
Selection precedence (highest first): CLI flags → env vars → `config/llm.yaml` →
built-in default (`anthropic` / `claude-opus-5`).
Wire a backend from inside the shell with `connect` — no environment fiddling:
| Command | Backend |
|---|---|
| `connect ollama llama3.1` | local Ollama (no API key) |
| `connect local http://localhost:1234/v1` | local OpenAI-compatible (LM Studio / llama.cpp / vLLM) |
| `connect anthropic --key sk-ant-...` | Anthropic cloud |
| `connect` · `connect test` · `connect save` | show / probe / persist the active backend |
Or from the command line and environment:
```bash
python -m exploit_builder --provider ollama --model llama3.1 recon 127.0.0.1 --analyze
python -m exploit_builder --provider openai_compatible --model gpt-4o-mini poc "..."
python -m exploit_builder providers # show what's active
```
Environment equivalents: `EBF_PROVIDER`, `EBF_MODEL`. API keys are read from the
env var each provider expects (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or the
`api_key_env` you set for an OpenAI-compatible endpoint). On Windows PowerShell:
```powershell
$env:ANTHROPIC_API_KEY = "sk-ant-..."
```
The `anthropic` package is only needed for the Anthropic provider; drop it if you
run purely local / OpenAI-compatible.
---
## Command reference
### Recon
| Command | Does |
|---|---|
| `recon [analyze] [report]` | TCP connect scan + banner grab, optional AI analysis/report |
| `services ` | service/version detection (`nmap -sV` if installed, else banner) |
| `fingerprint ` | HTTP tech + security headers + TLS cert + robots |
| `dirscan [wordlist]` | directory/content brute-force |
| `subdomains ` · `dns ` | DNS brute-force · records + crt.sh |
### Vulnerability & exploit intelligence
| Command | Does |
|---|---|
| `cve [ver]` · `cve hosts` | NVD lookup for a product / all recorded services |
| `exploit-suggest ` | recorded services → CVEs + reference links + existing public PoCs |
| `exploit-suggest ` | one CVE → all reference links + live GitHub PoCs |
| `exploit-fetch [--extract] ` | mirror existing public PoCs to `reports/poc/` for review (no exec) |
| `nuclei ` · `webscan [param]` | nuclei templates · active XSS/SQLi probe |
### Payloads & exploitation
| Command | Does |
|---|---|
| `shell ` | render a reverse-shell one-liner |
| `web ` · `encode ` | web-vuln markers · base64/url/hex/powershell |
| `pattern [hex]` | cyclic pattern, or find the offset of a captured value |
| `msfvenom [fmt] [out]` | payload generation (needs msfvenom) |
| `listen ` · `sessions` · `interact ` · `kill ` | reverse-shell handler |
### AI
| Command | Does |
|---|---|
| `poc ` | AI drafts PoC code for a vulnerability you've identified |
| `poc --from ` | AI adapts an existing local PoC to your target |
| `chat ` | grounded, streaming chat about the engagement |
| `agent [--background] ` | autonomous orchestrator; every tool call still scope-gated |
| `agents` · `usage` · `context` | agent sessions · token cost · AI context |
### Workspace, governance, meta
| Command | Does |
|---|---|
| `workspace new\|use\|list ` | engagement workspace (persists hosts/findings/loot) |
| `findings` · `hosts` · `loot` · `notes` · `audit` | view persisted data · action audit log |
| `export md\|html\|json\|pdf` | export a report of the workspace |
| `set dry-run on` · `set proxy ` · `set theme ` | log-only mode · SOCKS/HTTP proxy · recolor |
| `menu` · `providers` · `targets` · `status` | interactive menu · info panels |
| `!` | run a system command (no LLM, no scope gate) |
Tab autocompletes commands, templates, and scope targets; ↑/↓ walk history. On a
terminal that can't host the full TUI, OASAS falls back to a plain prompt.
---
## Exploit intelligence pipeline
The `exploit-suggest` / `exploit-fetch` / `poc` chain automates everything
*around* an exploit without shipping a library of weaponized code.
```mermaid
flowchart LR
SVC["service + version(from recon)"] --> CVE["NVD CVE match"]
CVE --> LINKS["reference linksNVD · MITRE-CVE · ATT&CK · CWE · CISA-KEV · ExploitDB · Metasploit"]
CVE --> POCS["existing public PoCsGitHub aggregator · searchsploit"]
POCS --> FETCH["exploit-fetchmirror to reports/poc/"]
FETCH --> EXTRACT["--extractpath-traversal-safe unpack"]
EXTRACT --> ADAPT["poc --fromAI adapts to your target"]
```
For each CVE, `exploit-suggest` prints deterministic, always-valid reference URLs
(NVD, MITRE CVE record, ATT&CK, the concrete MITRE **CWE** page, CISA KEV,
ExploitDB, Metasploit) plus a live lookup of real public GitHub PoC repos and any
local `searchsploit` matches:
```text
oasas> exploit-suggest CVE-2021-41773
[INFO] CVE-2021-41773
NVD https://nvd.nist.gov/vuln/detail/CVE-2021-41773
MITRE-CVE https://vulners.com/cve/CVE-2021-41773
ATT&CK https://attack.mitre.org/techniques/enterprise/
CWE-22 https://cwe.mitre.org/data/definitions/22.html
ExploitDB https://www.exploit-db.com/search?cve=2021-41773
Metasploit https://www.rapid7.com/db/?q=CVE-2021-41773&type=metasploit
GitHub PoCs (5):
[139*] https://github.com/inbug-team/CVE-2021-41773_CVE-2021-42013
[51*] https://github.com/thehackersbrain/CVE-2021-41773
[5*] https://github.com/Hydragyrum/CVE-2021-41773-Playground
```
**Design boundary.** The framework is an assistant, not an autonomous weaponizer:
- The AI agent has a **read-only** `lookup_exploit_intel` tool — it can pull
*references* to existing PoCs during a run, but never downloads or runs code.
- `exploit-fetch` is an explicit, human-invoked command. It mirrors public PoCs
to `reports/poc//` for review and writes a `SOURCES.md` provenance file.
Nothing is executed; GitHub repos arrive packed. `--extract` unpacks them
through a path-traversal-safe extractor (rejects `../` escapes, symlinks, and
device members). `reports/poc/` is gitignored — downloaded third-party code
never enters your repo.
- But you can always download extra-module for it if you want of course
---
## Rules of Engagement
The `roe:` block in `config/scope.yaml` enforces more than the target list:
| Field | Effect |
|---|---|
| `valid_from` / `valid_until` | engagement validity window; outside it, every active action is refused |
| `allowed_windows` | permitted time-of-day windows (local time) |
| `rate_limit` | throttle outbound connections (requests/sec, max concurrency) |
| `dry_run` | active actions are logged to the audit trail but send no packets |
Every active action is checked against the RoE and written to the per-workspace
audit log. Toggle log-only mode live with `set dry-run on`.
---
## One-shot commands
Every feature is also a normal subcommand for scripting:
```bash
python -m exploit_builder recon 192.168.56.10 --analyze --report
python -m exploit_builder payload shell --template python3 --lhost 192.168.56.1 --lport 4444
python -m exploit_builder payload pattern --length 200 --offset-of 6341346c
python -m exploit_builder poc "Stack buffer overflow at offset 76, no canary, x86 Linux" --language python
python -m exploit_builder agent "Enumerate 192.168.56.10 and write a report"
```
---
## Project layout
```
exploit_builder/
core/ scope enforcement, config, shared data models, workspace (SQLite)
modules/
recon/ port scan, service detect, fingerprint, content discovery, DNS
vuln/ NVD CVE lookup, exploit_intel (links + PoC fetch), nuclei, webscan
payloads/ reverse shells, web-vuln markers, encoders, cyclic patterns
exploit/ msfvenom wrapper, reverse-shell listener
ai/ provider layer + analyst, report writer, PoC assistant, agent
providers/ anthropic, ollama, openai_compatible backends + factory
report/ markdown / html / json / pdf rendering
tui/ OASAS shell: art, effects, intro, state, actions, shell, menu
cli.py command-line entrypoint (launches the shell by default)
config/ scope.yaml · llm.yaml · oasas.yaml (all gitignored — copy from .example)
reports/ generated reports; reports/poc/ holds fetched PoCs (gitignored)
workspaces/ one SQLite db per engagement (gitignored)
```
---
## Testing
There is no automated pytest suite yet; the framework is verified with the
reproducible manual pass below. Every active command is exercised against the
`127.0.0.1`/`localhost` targets the shipped `scope.yaml` authorizes.
```bash
# 1. imports / syntax
python -m compileall -q exploit_builder
# 2. scope gate — blocks the unauthorized, allows the authorized
python -m exploit_builder recon 8.8.8.8 # -> Blocked (not in scope)
python -m exploit_builder recon 127.0.0.1 # -> proceeds
# 3. full engagement flow (in the shell)
workspace new t; recon 127.0.0.1; services 127.0.0.1; hosts
exploit-suggest CVE-2021-41773
export md; export json; audit
# 4. exploit-fetch with safe extraction
exploit-fetch --extract CVE-2021-41773 # mirrors + unpacks public PoCs
# 5. offset finder handles both byte orders
python -m exploit_builder payload pattern --length 200 --offset-of 6341346c
```
Observed results (Python 3.11, Windows 11):
| Check | Result |
|---|---|
| `compileall` over the whole package | pass |
| Scope gate blocks `8.8.8.8`, allows `127.0.0.1` | pass — blocked action recorded in audit log |
| `recon` / `services` on `127.0.0.1` | 135/msrpc, 445/smb detected and persisted to SQLite |
| `export md \| json \| html` | all include hosts + open ports |
| `exploit-suggest CVE-2021-41773` | NVD/MITRE/ATT&CK/Metasploit/GitHub links + **CWE-22** + 5 live GitHub PoCs |
| `exploit-fetch --extract` | 3 repos mirrored and safely unpacked (12 files); `SOURCES.md` written |
| Malicious tarball (`../` escape + symlink to `/etc/passwd`) | both members rejected; nothing written outside the sandbox |
| `pattern --offset-of` | resolves for both big- and little-endian input |
| `set dry-run on` then `recon` | logged as `dry-run`, zero packets sent |
Priority for a real test suite: `core/scope.py` (CIDR matching, never-touch
denylist, RoE time-window math) and `modules/vuln/exploit_intel._safe_extract`
(archive hardening) — both are pure logic and easy to pin down.
---
## Extending it
- **Recon module** — add a scope-gated function under `modules/recon/`, wire it
into `cli.py` and (optionally) the agent orchestrator's tool list.
- **Payload template** — add to the relevant dict in `modules/payloads/`.
- **AI capability** — add a function to `modules/ai/` that takes a `provider` and
calls `provider.complete()` / `complete_json()` / `chat()`; it works across
every backend automatically.
- **LLM backend** — subclass `BaseProvider` in `modules/ai/providers/`, implement
`chat()`, and register it in the factory in `providers/__init__.py`.
- **Drop-in plugin** — a `.py` in `plugins/` exposing `register(api)` adds shell
commands without touching core (see `plugins/example.py`).
Optional external tools auto-detected on PATH: **nmap**, **nuclei**, **msfvenom**,
**searchsploit**. Optional Python extras: `weasyprint` (PDF export), `pysocks`
(SOCKS proxy). All degrade gracefully when absent.
---
## Responsible use
Only point this at systems you own or have explicit written authorization to test
— your own lab VMs, or CTF/training platforms (HackTheBox, TryHackMe, PortSwigger
Labs). `config/scope.yaml` is your authorization record; keep it accurate, and
don't share generated payloads, fetched PoCs, or reports outside that
authorization. Downloaded PoC code (`reports/poc/`) is untrusted third-party
material — read it before running anything.
MIT licensed. Made by aknxpp / sigmawolf.
## Soon I'll end fully fine tunning my LLM and make it ready for cybersecurity auto-offensive usage ASAP, and I'll make it uncensored
---
