ONUS - Open-source AI-assisted VAPT platform for automate

项目说明

ONUS - Automated Assessment & Penetration Testing

![CI]()

<p align="center">
<a href=" src="docs/screenshots/hero-landing.png" alt="ONUS - Find security risks before attackers do." width="820"></a>
</p>

Built by ma.

A locally-hosted, air-gapped VAPT tool: point it at an authorized target
domain and it runs 8 scanning modules in parallel, deterministically scores
every finding (CVSS v3.1), optionally adds AI-generated plain-English
descriptions via a local LLM, and produces a PDF report plus a live web
dashboard. No external API calls - e runs on your own network.

> Two ways to run ONUS:
> - Self-hosted (this repo): docker compose up → enter a domain → tick the
> authorization box → scan. No account, no sign-in, no email -
> it's single-operator by design, and e below covers this path.
> - Hosted: a managed instance is live at tryonus.tech.
> It layers on production-only features (accounts / OAuth sign-in, a scan
> queue, per-user history) that default off in this repo, so self-hosting
> stays simple. See Self-hosted .

Features

8 parallel scanning modules (Celery) - network recon

(ports/services/subdomains/DNS/WHOIS), web app scanning (ZAP + Nikto +
Katana), SSL/TLS config, HTTP security headers, OWASP Top 10 checks, tech
fingerprinting/WAF detection, C (Nuclei), directory enumeration
(FFUF).

Deterministic CVSS v3.1 scoring - se, C/,

priority, and OWASP category are computed from a rule catalogue, never
guessed by an LLM. Two runs of the same scan produce byte-identical
numeric fields.

Confidence - findings are passively re-checked

(non-destructi only) and tagged confirmed / probable /
un rather than silently dropped.

Optional local AI analysis - Ollama + Qwen 2.5 7B turns scored

findings into plain-English descriptions and remediation steps. Fully
air-gapped; the tool works without it (see Quick start below).

Context-aware, actionable remediation - every finding ends with a

concrete next step. Stable issues use deterministic templates; genuinely
context-dependent ones use the AI; and managed-platform detection
( / Cloudflare / Netlify / GitHub Pages / …) means a platform-owned
TLS finding says who controls that layer and what to do next, instead of
impossible "edit your ser" advice.

PDF report + web dashboard - WeasyPrint-rendered report and a Next.js

dashboard, both driven by the same scored/described findings.

Technical write-up

Where the LLM Stops: Deterministic Scoring in an AI-Assisted VAPT Pipeline

A technical deep dive into ONUS's architecture, passi , deterministic C, and the boundary between security-critical logic and LLM-assisted explanations and remediation.

Self-hosted

| | Self-hosted (this repo) | Hosted (tryonus.tech) |
|---|---|---|
| Setup | docker compose up | none - just open the site |
| Sign-in | none - single operator | account / Google / GitHub OAuth |
| Scan flow | domain → authorization box → scan | same, after signing in |
| Extras | - | scan queue, per-user history, hosted email |
| Runs on | your own network, air-gapped | managed cloud |

The self-hosted default path is intentionally the simple one: **no sign-up, no
email , no OAuth**. The hosted-only features (authentication, scan
queue) li config flags that default off (REQUIRE_AUTH=false,
HOSTED_QUEUE_ENABLED=false; see Configuration) and are not
set in docker-compose.yml - so running ONUS locally never puts you behind a
login. Prefer zero setup? Use the hosted site at
tryonus.tech.

Screenshots

| New Scan | Live Scan Status |
|---|---|
| !New Scan form | !Scan Status page |

| Report Dashboard | Scans Discovery |
|---|---|
| !Report dashboard | !Scans discovery dashboard |

Architecture

<img src="docs/screenshots/architecture.png" alt="Six-layer architecture diagram" width="420">

Six layers: Next.js frontend → FastAPI → Celery/Redis → 8 parallel scanning
modules → Ollama (Qwen 2.5 7B) → WeasyPrint PDF + dashboard. Full details in
ARCHITECTURE.md (schemas, contracts, guardrails) and
docs/QUICK_REF.md (quick lookup for common changes).

Prerequisites

Docker + Docker Compose v2

~8GB free disk. The built images total ~6.8GB (backend and worker are

~3.25GB each - they bundle Nuclei templates and a headless Chromium via
Playwright - plus a ~270MB frontend), and the build itself needs headroom
on top.

~6GB free RAM. The ZAP sidecar alone is capped at 4GB (mem_limit: 4g),

and Postgres, Redis, the API, the worker and the frontend run alongside it.

First build takes roughly 10-15 minutes on a decent connection.

Quick start

> See Prerequisites above: ~8GB disk and ~6GB RAM, and expect a 10-15 minute
> first build.

Open , enter a domain, tick the authorization box, and
start the scan.

No sign-in, sign-up, or email . Self-hosted ONUS is
single-operator by default - there's no account step between opening the
dashboard and scanning.

This works with no Ollama install. C/priority scoring is
always deterministic (analysis/c.py) - without Ollama running,
findings just get a rule-based description template instead of AI-generated
prose. See "Optional: enable AI-generated descriptions" below to turn that on.

Zero API keys are required to run this tool. Every scanning tool it
wraps (nmap, ZAP, Nikto, testssl.sh, Nuclei, Amass, Naabu, httpx, WhatWeb,
WAFW00F, FFUF) and Ollama itself work with no key at all. The subfinder
config copy step above is the one optional exception - leaving it as the
empty template is fine, subfinder just runs with free/public sources only.
To deepen subdomain enumeration, you can add up to two free-tier keys to
that file before starting: a GitHub personal access token and a
ProjectDiscovery Chaos API key - see
the comments inside pro.yaml.example.

Optional: enable AI-generated descriptions

Ollama runs natively on the host (not in Docker) so it can use the
host's GPU directly; containers reach it via host.docker.internal.

1. Install Ollama on the host:
2. Pull the model: ollama pull qwen2.5:7b
3. Make Ollama reachable from Docker containers (Ollama defaults to
127.0.0.1-only, which Docker's bridge network cannot reach):

Add under [Service]:

Save, then:

Note: this makes Ollama reachable from your local network, not just
Docker - fine on a personal machine, worth a firewall rule on a shared one.
4. : curl
5. Restart the backend/worker so they pick it up: docker compose restart backend worker

Optional: practice targets

The compose file also defines 12 intentionally- practice apps
(Juice Shop, DVWA, bWAPP, Mutillidae, NodeGoat, D behind a
ModSecurity WAF, Metasploitable2, WebGoat) for trying the scanner against
something without needing your own authorized target. They're gated behind
a Compose profile so they ne/start by default:

**Warning: these are intentionally-, some genuinely backdoored,
services** (Metasploitable2 ships a li backdoor). Only run the
targets profile on a machine that isn't reachable from the internet or a
shared network - never on a public cloud instance or an exposed host.

Most of these run from prebuilt images and need nothing extra. Two -
nodegoat and d - build from source that isn't into
this repo and must be cloned first:

Published ports once running: Juice Shop :3001, DVWA :8081, bWAPP
:8083, Mutillidae :8084, NodeGoat :8085, DVWP (via WAF, TLS) :8444,
WebGoat :8082. Metasploitable2 publishes no host port (reachable only from
backend/worker o's internal network) since it exposes real
backdoored/unauthenticated network services.

Configuration

Env vars, set via .env (copied from .en):

| | Default | Purpose |
|---|---|---|
| POSTGRES_PASSWORD | | Database password |
| SECRET_KEY | change_me_to_a_long_random_string | Backend secret key |
| ALLOWED_HOSTS | localhost,127.0.0.1 | FastAPI allowed hosts |
| OLLAMA_URL | | Where the backend/worker reach Ollama |
| SCAN_TIMEOUT_MULTIPLIER | 1.5 | Scales every module's tool/Celery timeout - real-world targets are slower than lab targets; drop to 1.0 for lab-tuned timings |
| MAX_CONCURRENT_SCANS | 3 | Concurrent-scan cap (resource-exhaustion / target-politeness guard, also sizes the DB connection pool) |
| ONUS_ENV | de | de (self-hosted localhost — weak secrets only warn) or production (weak SECRET_KEY/Postgres password become a hard boot failure) |

The POSTGRES_PASSWORD/SECRET_KEY defaults above are demo-only -
they're fine for a local/personal instance but change both before deploying
anywhere reachable by anyone else. This is now *enforced*, not just advised:
set ONUS_EN (or turn on hosted auth) and the backend **refuses to
start** while either is still a default/placeholder. Generate a strong key with
python -c "import secrets; print(secrets.token_urlsafe(48))".

Hosted-only features are off by default. REQUIRE_AUTH (accounts / OAuth
sign-in) and HOSTED_QUEUE_ENABLED (scan queue) both default to false and
aren't set in docker-compose.yml, so self-hosted ONUS ne you behind
a login or a queue. Leave them off unless you're intentionally building a
multi-user hosted deployment - the managed tryonus.tech
instance is the one that turns them on.

Analytics (optional)

ONUS has no analytics by default - nothing loads and no data leaves the
browser. To collect anonymous product-usage metrics on your own deployment,
set a single Google Analytics 4 Measurement ID:

It's a frontend build-time , so set it in the frontend build
en (a /host env var, or frontend/.en for a local
npm run build). When set, GA loads only in production builds and tracks
page views plus a few product events (e.g. scan_started, scan_completed,
report_downloaded). Custom events go through the typed helper in
frontend/lib/analytics.ts -
trackEvent('scan_started').

Privacy: only anonymous, low-cardinality usage events are sent - never
scanned domains, scan results, findings, report contents, the authorization
state, or any personal data. Leave NEXT_PUBLIC_GA_ID unset and ONUS behaves
exactly as before; analytics is entirely opt-in.

API docs

FastAPI generates interacti docs for free - once the backend is
running, open .

Stop

Logs

Testing &

655 automated backend tests as of this writing. Beyond the unit/integration
suite, the tool has been exercised end-to-end during de: 79 real
scans executed and 124 PDF reports generated against nine deliberately-
practice applications (DVWA, Juice Shop, Mutillidae, NodeGoat,
bWAPP, WebGoat, Metasploitable2, D behind a WAF) plus one
authorized public target (testphp..com) - not hypothetical numbers.
Only ever scan targets you are explicitly authorized to test - see
docs/test_findings.md for the practice targets
used during de.

Documentation

ARCHITECTURE.md - full architecture, schemas, and

the contracts a change should ne. Read this before making a
non-trivial change.

docs/QUICK_REF.md - run commands, folder

responsibilities, "where do I make this change."

docs/scanners.md - reasoning behind each scanning

module's timing/flag design.

docs/ai.md - Ollama timeout/context tuning, why scoring

moved off the LLM entirely.

docs/docker.md - Docker de notes and build

gotchas.

docs/troubleshooting.md - how to manually

test any module/stage in isolation.

docs/roadmap.md - historical build sequence

(build is complete).

CONTRIBUTING.md - de, tests, PR expectations.

License

MIT - see LICENSE.

Authorized use only

Scanning targets without explicit written authorization is illegal under the
IT Act 2000 (India) and equi international statutes. This tool
requires authorization confirmation on every scan and logs the operator +
timestamp for accountability.

项目信息

开发语言：Python

Star 数：12

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Open-source AI-assisted VAPT platform for automated vulnerability scanning, evidence verification, deterministic CVSS scoring, and actionable security remediation. Findings are explained in plain english language for you to act on without security knowledge.[Scan your website for vulnerabilities]展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。