diff --git a/README.md b/README.md index 0ecf11a..26a7cbf 100644 --- a/README.md +++ b/README.md @@ -1,186 +1,384 @@ -# NICE_SCAN +

+
+ Version + CI + Release + Latest Release + License +

-**Fast. Precise. Intelligent.** — Modern Security Reconnaissance Engine +

+ Fast. Precise. Intelligent.
+ Modern Security Reconnaissance Engine — Autonomous Attack Chaining & Real Data Extraction +

-NICE_SCAN is a professional-grade CLI tool for authorized security reconnaissance. It combines high-performance HTTP scanning, intelligent technology fingerprinting, and an **autonomous hack agent** with a decision engine that chains attacks automatically. +
-```bash -# Quick start — full autonomous hack in one command +## Overview + +NICE_SCAN is a professional-grade offensive security tool that combines high-performance HTTP scanning, intelligent technology fingerprinting, and an **autonomous Decision Engine** that chains attacks, extracts real data, and generates professional HTML reports — all from a single command. + +```shell +# ── Full autonomous hack ──────────────────────────── nice_scan hack example.com -R report.html + +# ── One-line install ──────────────────────────────── +curl -sfL https://raw.githubusercontent.com/NICE-DEV226/nice-Scan/main/scripts/install.sh | sh ``` -## Installation +
-### Option 1: Go install (requires Go 1.24+) -```bash -go install github.com/NICE-DEV226/nice-Scan/cmd/nice_scan@latest +## Features + +### Autonomous Hack Agent +Run `nice_scan hack target.com` and the Decision Engine autonomously executes 14 attack actions with forward-chaining: + + + + + + + + + + +
+ +**🔍 Reconnaissance** +- Passive recon (crt.sh, Wayback Machine — zero target requests) +- Web crawl (BFS discovery: pages, forms, JS files) +- Fuzzing (42 paths, 16 params) +- Concurrent port scan (20 goroutines, 30 ports × 3 hosts) +- S3 bucket enumeration (20 candidates) + + + +**💥 Exploitation & Chaining** +- SQLi detection + auto data extraction (user tables) +- LFI detection + auto file read (`/etc/passwd`, configs) +- CMD injection + auto shell execution +- File upload + auto web shell deployment +- JWT forge (`alg=none` + 40 common secrets) +- XSS, GraphQL introspection, login brute-force + +
+ +**🧠 Decision Engine** +- 10 attack chain patterns (CORS→XSS, JWT→Admin, Secrets→Cloud, Upload→RCE) +- Forward-chaining: each finding auto-spawns exploit modules +- Thread-safe dynamic planner with priority queue +- Session management (persistent cookies, tokens, JWT) +- Knowledge base with auto-capability derivation + + + +**📊 Professional Output** +- HTML attack reports (dark theme, risk scoring, findings timeline) +- Extracted data saved to `reports/{target}/` (SQL dumps, LFI files, shell output, S3 buckets) +- Real-time TUI dashboard with progress bars + findings stream +- Interactive REPL shell (command history, session context) +- JSON output for CI/CD pipelines + +
+ +
+ +## Quick Start + +```shell +# Full autonomous hack — 14 actions, auto-chaining, HTML report +nice_scan hack example.com -R report.html + +# Interactive reconnaissance shell +nice_scan shell + +# Real-time dashboard with live findings +nice_scan scan example.com -i + +# Time-boxed engagement (ideal for bug bounties) +nice_scan hack target.com --timeout 30s -R report.html + +# Exploitation modules +nice_scan exploit https://example.com --login --idor 1-100 + +# Technology fingerprinting +nice_scan tech https://example.com + +# JSON output +nice_scan scan https://example.com --json ``` -### Option 2: One-liner installer -**macOS / Linux:** -```bash -curl -sfL https://raw.githubusercontent.com/NICE-DEV226/nice-Scan/main/scripts/install.sh | sh +
+ +## Installation + +### Package Managers + +
+Scoop (Windows) + +```powershell +scoop bucket add nice-scan https://github.com/NICE-DEV226/nice-Scan +scoop install nice-scan/nice_scan ``` +
+ +
+Winget (Windows) -**Windows (PowerShell 7+):** ```powershell -powershell -ExecutionPolicy Bypass -c "iex \"& { $(irm https://raw.githubusercontent.com/NICE-DEV226/nice-Scan/main/scripts/install.ps1) }\"" +winget install --id NICE-DEV226.nice-Scan ``` +
-### Option 3: Download pre-built binary -Download the latest release for your platform from the [Releases page](https://github.com/NICE-DEV226/nice-Scan/releases). +
+Homebrew (macOS / Linux) -### Option 4: Build from source ```bash -git clone https://github.com/NICE-DEV226/nice-Scan.git -cd nice-Scan -make build -# or: go build -o nice_scan ./cmd/nice_scan +brew install NICE-DEV226/tap/nice-scan ``` +
-## Quick Start +### Direct Install + +
+Go Install (cross-platform, requires Go 1.24+) ```bash -# See all commands -nice_scan --help +go install github.com/NICE-DEV226/nice-Scan/cmd/nice_scan@latest +``` +
-# Full autonomous hack (most powerful — try this first!) -nice_scan hack https://example.com +
+One-liner Installer (macOS / Linux) -# With HTML report -nice_scan hack https://example.com -R report.html +```bash +curl -sfL https://raw.githubusercontent.com/NICE-DEV226/nice-Scan/main/scripts/install.sh | sh +``` +
-# With custom timeout (default: 5s per action) -nice_scan hack https://example.com --timeout 10s -R report.html +
+One-liner Installer (Windows PowerShell 7+) -# Standard reconnaissance scan -nice_scan scan https://example.com +```powershell +powershell -ExecutionPolicy Bypass -c "iex \"& { $(irm https://raw.githubusercontent.com/NICE-DEV226/nice-Scan/main/scripts/install.ps1) }\"" +``` +
-# Technology detection only -nice_scan tech https://example.com +
+Manual — download from GitHub Releases -# TLS analysis -nice_scan tls https://example.com +Download the latest binary for your platform from the [Releases page](https://github.com/NICE-DEV226/nice-Scan/releases), verify the checksums, and extract. -# Active exploitation modules -nice_scan exploit https://example.com --login --idor 1-100 +```bash +# Example: Linux amd64 +curl -sSfL https://github.com/NICE-DEV226/nice-Scan/releases/latest/download/nice_scan_latest_linux_amd64.tar.gz | tar xz +sudo mv nice_scan /usr/local/bin/ +``` +
-# Interactive shell (persistent session) -nice_scan shell +### Build from Source -# JSON output for CI/CD -nice_scan scan https://example.com --json +```bash +git clone https://github.com/NICE-DEV226/nice-Scan.git +cd nice-Scan +make build +# or: go build -o nice_scan ./cmd/nice_scan ``` -## Features +
-### 🧠 Autonomous Hack Agent -Run `nice_scan hack target.com` and the Decision Engine autonomously: -1. **Passive recon** — crt.sh, Wayback Machine (no requests to target) -2. **Web crawl** — BFS discovery of pages, forms, endpoints, JS files -3. **Fuzzing** — hidden endpoints (42 paths) and parameter discovery (16 params) -4. **Port scan** — concurrent TCP connect (30 ports × 3 hosts) -5. **Attack modules** — JWT forge, SQLi, XSS, LFI, CMD injection, file upload, GraphQL introspection -6. **Login bruteforce** — 40 common credentials against discovered login forms -7. **S3 enumeration** — 20 bucket name candidates, concurrent checking -8. **OOB callback server** — blind SSRF/SSTI/XSS detection -9. **Attack chain detection** — CORS→XSS, JWT→Admin, Secrets→Cloud, Upload→RCE, and more -10. **Real data extraction** — SQLi → user dump, LFI → file read, CMD → shell output, S3 → bucket dump +## Attack Walkthrough ``` $ nice_scan hack example.com --timeout 15s -R report.html - NICE HACKER — DECISION ENGINE + + ◈ NICE HACKER — DECISION ENGINE Target: https://example.com Actions loaded: 14 - Step 4 [19s] ─ + Step 1 [0s] ────────────────────────────────── + ┌────────────────────────────────────────────────┐ + │ Passive Reconnaissance │ + └────────────────────────────────────────────────┘ + ▸ INFO crt.sh subdomains: 3 found (+ wayback) + + Step 2 [2s] ────────────────────────────────── + ┌────────────────────────────────────────────────┐ + │ Crawl Endpoints │ + └────────────────────────────────────────────────┘ + ▸ INFO Paths discovered: 47 + + Step 3 [4s] ────────────────────────────────── + ┌────────────────────────────────────────────────┐ + │ SQL Injection Checking 16 params │ + └────────────────────────────────────────────────┘ + !! CRITICAL SQLi: login.php (param: id) + ◈ Spawned: SQLi Data Extractor + + Step 4 [5s] ────────────────────────────────── ┌────────────────────────────────────────────────┐ - │ S3 Bucket Enumeration Check subdomains │ + │ SQLi Data Extraction Dump user tables │ └────────────────────────────────────────────────┘ - !! CRITICAL Public S3 bucket: example-files - ◈ Spawned: S3 Bucket Dumper + !! CRITICAL Users extracted: 142 records - Step 5 [23s] ─ + Step 5 [7s] ────────────────────────────────── ┌────────────────────────────────────────────────┐ - │ S3 Bucket Dumper List + download contents │ + │ Local File Inclusion │ └────────────────────────────────────────────────┘ - !! CRITICAL S3 bucket listing: 18 files - ▸ HIGH S3 file: samples/config.json + !! CRITICAL LFI: /etc/passwd via page= param + ◈ Spawned: LFI File Reader + + Step 6 [8s] ────────────────────────────────── + ┌────────────────────────────────────────────────┐ + │ LFI File Read Extract sensitive files │ + └────────────────────────────────────────────────┘ + !! CRITICAL Files: 12 (passwd, shadow, .env, config...) + + Step 7 [10s] ───────────────────────────────── + ┌────────────────────────────────────────────────┐ + │ Attack Chain Detection │ + └────────────────────────────────────────────────┘ + ◈ CORS + XSS Chain: api allows all origins + ◈ JWT + Admin Chain: weak secret forgeable + ◈ Secrets + Cloud Chain: 8 credentials in extracted files + + Step 8 [12s] ───────────────────────────────── + ┌────────────────────────────────────────────────┐ + │ Report Generation │ + └────────────────────────────────────────────────┘ + ✓ Risk Score: 10.0 / 10 + ✓ Report: report.html + + ── Extraction Summary ── + 📁 reports/example.com/ + ├── sql_dump/users.sql (142 records) + ├── lfi_files/passwd + ├── lfi_files/shadow + ├── lfi_files/config.php + └── credentials.txt (8 credentials) ``` -### 🔍 Full Scan Suite -- **High-Performance HTTP Engine** — Connection pooling, HTTP/2, keep-alive, adaptive retries -- **Technology Fingerprinting** — 165 signatures: detect frameworks, CMS, CDNs, WAFs, cloud providers -- **Security Header Analysis** — CSP, HSTS, CORS, cookie security flags -- **TLS Analysis** — Version, cipher suites, certificate validation -- **Exposure Detection** — .env, .git, source maps, backups, directory listing -- **Active Exploitation** — Login brute, IDOR, privilege escalation, token reuse, registration, password reset, session fixation +
+ +## Trust & Supply Chain Security + +Every release is cryptographically signed and verifiable. NICE_SCAN follows SLSA Level 2 practices with full supply chain transparency. -## HTML Reports +| Layer | Method | Verification Command | +|-------|--------|---------------------| +| **Code Integrity** | All commits GPG-signed | `git log --show-signature` | +| **Binary Integrity** | SHA256 checksums | `sha256sum --check checksums.txt` | +| **Release Authenticity** | GPG-signed checksums | `gpg --verify checksums.txt.sig checksums.txt` | +| **Build Provenance** | Sigstore/cosign (keyless OIDC) | `cosign verify-blob --bundle checksums.sigstore.json checksums.txt` | +| **Dependency Transparency** | SPDX SBOM | `syft scan nice_scan --from-release NICE-DEV226/nice-Scan:v0.1.0` | +| **Verifiable Build** | `gh attestation verify` | `gh attestation verify nice_scan_linux_amd64.tar.gz --repo NICE-DEV226/nice-Scan` | -Use `-R report.html` with `scan`, `audit`, or `hack` commands to generate a detailed HTML attack report with severity breakdown, risk scoring, and all findings. +### Quick Verification ```bash -nice_scan hack https://example.com -R report.html -# → Opens report.html in browser +# Download release assets +gh release download v0.1.0 --pattern "checksums*" -R NICE-DEV226/nice-Scan + +# Verify SHA256 +sha256sum --check nice_scan_0.1.0_checksums.txt --ignore-missing + +# Verify GPG signature +gpg --verify nice_scan_0.1.0_checksums.txt.sig nice_scan_0.1.0_checksums.txt + +# Verify Sigstore (keyless OIDC) +cosign verify-blob --bundle nice_scan_0.1.0_checksums.txt.sigstore.json nice_scan_0.1.0_checksums.txt + +# Most trustworthy: build from source +git clone https://github.com/NICE-DEV226/nice-Scan.git && cd nice-Scan && go build ./cmd/nice_scan ``` +> **Note:** The project GPG public key is published to `keyserver.ubuntu.com` (fingerprint: `4CE466095C5B3185883288C593FBFE29F62FA4DB`). Verify with `gpg --recv-keys 93FBFE29F62FA4DB`. + +See [SECURITY.md](SECURITY.md) for the full security policy and [cosign.pub](cosign.pub) for the cosign public key. + +
+ +## Commands + +| Command | Description | +|---------|-------------| +| `hack ` | **Full autonomous attack chain** — 14 actions, auto-chaining, data extraction | +| `scan ` | Standard reconnaissance scan (headers, TLS, fingerprint, endpoints) | +| `tech ` | Technology fingerprinting only (165 signatures) | +| `tls ` | TLS/SSL analysis (ciphers, certs, protocol versions) | +| `exploit ` | Active exploitation modules (login brute, IDOR, privesc, token) | +| `shell` | Interactive REPL reconnaissance shell | +| `--version` | Display version | +| `--help` | Display help | + +
+ ## Development ```bash # Build make build -# Run (with optional args) +# Run with args make run ARGS="hack example.com --timeout 10s" -# Test +# Test with race detection make test -# Cross-compile for all platforms +# Cross-compile (linux + windows + darwin, amd64 + arm64) make build-all # Lint make lint -``` - -## Trust & Security -NICE_SCAN takes supply chain security seriously. Every release is cryptographically verified. +# Vet +make vet -| What | How | -|------|-----| -| **Code integrity** | All commits GPG-signed | -| **Binary integrity** | SHA256 checksums published for every release | -| **Release authenticity** | Checksums file signed with project GPG key (`.sig`) | -| **Build provenance** | Sigstore/cosign attestation (SLSA Level 2) | -| **Dependency transparency** | SPDX SBOM in every release | -| **Auditability** | Full source at [github.com/NICE-DEV226/nice-Scan](https://github.com/NICE-DEV226/nice-Scan) | +# Goreleaser snapshot +make snapshot -### Verify before running - -```bash -# Download release assets -gh release download v0.2.0 --pattern "checksums*" -R NICE-DEV226/nice-Scan - -# Verify SHA256 -sha256sum --check nice_scan_v0.2.0_checksums.txt --ignore-missing +# Full release +make release +``` -# Verify GPG signature -gpg --verify nice_scan_v0.2.0_checksums.txt.sig nice_scan_v0.2.0_checksums.txt +### Architecture -# Most trustworthy: build from source -git clone https://github.com/NICE-DEV226/nice-Scan.git && cd nice-Scan && go build ./cmd/nice_scan +``` +cmd/nice_scan/ CLI entry point (Cobra commands) +internal/ + hacker/ Decision Engine (types, planner, chaining, knowledge, brain) + engine/ Analysis modules (SQLi, XSS, CORS, TLS, tokens, auth, etc.) + exploit/ Exploitation modules (login, IDOR, privesc, token, session) + fingerprint/ Technology fingerprinting (165+ signatures) + transport/ HTTP client (connection pooling, retries, H2) + shell/ Interactive REPL shell + tui/ Terminal UI (live dashboard) + output/ Output renderers (terminal, JSON, HTML) + types/ Shared types +scripts/ Install scripts (install.sh, install.ps1) +docs/ Landing page & documentation ``` -See [SECURITY.md](SECURITY.md) for full details. +
## Documentation - [Architecture Overview](docs/architecture/overview.md) - [Transport Layer](docs/architecture/transport.md) -- [ARCHITECTURE.md](ARCHITECTURE.md) — Detailed system architecture +- [ARCHITECTURE.md](ARCHITECTURE.md) — Detailed system design +- [CONTRIBUTING.md](CONTRIBUTING.md) — Development workflow & conventions +- [SECURITY.md](SECURITY.md) — Security policy & vulnerability reporting + +
## Legal -This tool is intended exclusively for authorized security testing of systems you own or have explicit permission to test. Unauthorized use may violate applicable laws. +This tool is intended exclusively for **authorized security testing** of systems you own or have explicit permission to test. Unauthorized use may violate applicable laws. The authors assume no liability and are not responsible for any misuse or damage caused by this tool. + +--- + +

+ Built with Go · Cobra · BubbleTea · LipGloss
+ Released under MIT License · © 2026 NICE-DEV226 +