docs: Update README with comprehensive CLI commands and Docker options

Author: vishnurajkv

README.md

@@ -1,40 +1,57 @@
-# SecNode API Pentester
+# SecNode API
 
-SecNode is an autonomous API security testing agent. It starts with an OpenAPI/Swagger spec and uses a mix of traditional security tools and LLM reasoning to find vulnerabilities like BOLA, mass assignment, and business logic flaws.
+[![CI](https://github.com/SecNode/API-PENTESTER/actions/workflows/secnode-pentest.yml/badge.svg)](https://github.com/SecNode/API-PENTESTER/actions/workflows/secnode-pentest.yml)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](./LICENSE)
+
+AI-augmented, schema-driven API penetration testing from OpenAPI/Swagger specs, with asynchronous execution and structured reporting.
+
+## Why SecNode API
+
+SecNode API helps security engineers and backend teams run repeatable API risk assessments in staging and CI without writing one-off test scripts for every target.
+
+- Ingests local or remote OpenAPI/Swagger schema files
+- **Phase 1c Deep Recon:** Automatically analyzes body schemas and uses AI to plan `arjun` parameter discovery.
+- **Tool Orchestration:** Integrates `nuclei`, `sqlmap`, and `dirsearch` directly into the agent reasoning.
+- **AI-Driven Logic:** Uses an LLM to understand API behavior and generate adversarial test cases.
+- **Autonomous Agent:** Supports iterative replanning with request budgets and finding deduplication.
+- **Reporting:** Produces both human-readable Markdown and machine-readable JSON findings.
 
 ## How it works
 
-The pipeline runs in four distinct stages to ensure both shallow and deep coverage:
+The pipeline runs in four distinct stages:
 
-1.  **Reconnaissance (Phase 1a/1b/1c)**
-    - **Active Fuzzing:** Probes for undocumented paths, admin panels, and common file exposures.
-    - **Tool Orchestration:** Runs `dirsearch` for directory discovery and `nuclei` for template-based scanning.
-    - **Deep Analysis (New):** Deep-parses the API specification to pull out body fields and nested parameters. It then uses AI to plan and run `arjun` for hidden parameter discovery.
+1.  **Reconnaissance (Phase 1a-c)**
+    - **Active Fuzzing:** Probes for undocumented paths and common exposures.
+    - **Tool Orchestration:** Runs `dirsearch` and `nuclei` for automated scanning.
+    - **Deep Recon:** Deep-parses the spec for body fields and uses AI to find hidden parameters with `arjun`.
 2.  **AI Analysis (Phase 2)**
-    - An LLM analyzes the discovered API structure to understand business context and identify high-risk flows.
-    - It generates adversarial test cases specifically tailored to the API's logic.
+    - An LLM builds a business context model and identifies high-risk flows.
+    - Generates adversarial test cases tailored to the specific API logic.
 3.  **Execution & Validation (Phase 3)**
-    - The agent executes the tests using adaptive concurrency.
-    - Responses are analyzed by the AI to distinguish between real vulnerabilities and false positives.
+    - Async execution of generated tests.
+    - AI-based validation to confirm findings and assign CVSS scores.
 4.  **Deduplication (Phase 4)**
-    - The agent clusters findings sharing a root cause so you don't get 50 reports for the same underlying bug.
+    - Clusters duplicate findings by root cause to provide a clean, actionable report.
 
-## Getting Started
+## Installation
 
-### Prerequisites
-- Python 3.10+
-- An API key for OpenAI, Anthropic, or Nebius
-- Docker (recommended for running the integrated tools)
+### Requirements
+- Python 3.9+
+- LLM API Key (OpenAI, Anthropic, or Nebius)
+- Docker (optional, but recommended for tool orchestration)
 
-### Installation
+### Local Setup
 ```bash
 git clone https://github.com/SecNode/API-PENTESTER.git
 cd API-PENTESTER
 pip install -e .
 ```
 
-### Configuration
-Set your LLM provider as an environment variable:
+## Configuration
+
+Set your provider credentials before running scans:
+
 ```bash
 # Example for DeepSeek via Nebius
 export SECNODE_LLM="nebius/deepseek-ai/DeepSeek-V3.2"
@@ -44,30 +61,72 @@ export NEBIUS_API_BASE="https://api.tokenfactory.nebius.com/v1/"
 
 ## Usage
 
-Run a basic scan:
+### CLI Commands
+
+Run against a remote schema:
 ```bash
-secnodeapi --target http://example.com/swagger.json
+secnodeapi --target https://api.example.com/swagger.json
 ```
 
-Run with Docker (easiest way to use all tools):
+Advanced options:
+```bash
+# Dry run to see generated tests
+secnodeapi --target ./openapi.yaml --dry-run --dry-run-output tests.json
+
+# Authenticated scanning
+secnodeapi --target http://api.local/spec --auth-header "Authorization: Bearer <token>"
+
+# Using a proxy (e.g. Burp Suite)
+secnodeapi --target http://api.local/spec --proxy http://127.0.0.1:8080 --insecure
+
+# Agent fine-tuning
+secnodeapi --target http://api.local/spec --mode agent --request-budget 500 --max-iterations 5
+```
+
+### Full CLI Options
+| Option | Description |
+|---|---|
+| `--target` | URL or local path to OpenAPI schema (required) |
+| `--mode` | `agent` (default) or `legacy` execution pipeline |
+| `--concurrency` | Concurrent request workers |
+| `--auth-header` | Single inline auth header |
+| `--auth-file` | JSON file of auth headers |
+| `--identities-file` | JSON identities for differential auth testing |
+| `--schema-only` | Output normalized API structure and exit |
+| `--dry-run` | Generate tests without executing |
+| `--request-budget` | Max request count in agent mode |
+| `--max-iterations` | Max plan/execute loops in agent mode |
+| `--proxy` | Route traffic via proxy |
+| `--insecure` | Disable TLS verification |
+
+## Docker Support
+
+The easiest way to run SecNode with all integrated tools (`nuclei`, `sqlmap`, `arjun`, `dirsearch`) is via Docker.
+
+### Build
 ```bash
 docker build -t secnodeapi .
-docker run --rm -v $(pwd)/results:/app/results -e NEBIUS_API_KEY="..." secnodeapi --target http://example.com/swagger.json
 ```
 
-## Project Structure
-- `src/secnodeapi/services/recon.py`: The initial path fuzzer.
-- `src/secnodeapi/services/deep_recon.py`: The new AI-driven parameter discovery layer.
-- `src/secnodeapi/services/tool_orchestrator.py`: Orchestrates Nuclei, SQLMap, etc.
-- `src/secnodeapi/ai/`: LLM logic for analysis, test generation, and validation.
-- `src/secnodeapi/tools/runners/`: Adapters for external CLI tools.
+### Run
+```bash
+docker run --rm \
+  -v $(pwd)/results:/app/results \
+  -e NEBIUS_API_KEY="your-key" \
+  secnodeapi --target http://api.example.com/swagger.json
+```
+
+### Docker Compose
+```bash
+docker-compose run --rm secnodeapi --target http://api.example.com/swagger.json
+```
 
 ## Shout-outs
-This project stands on the shoulders of some incredible open-source security tools:
-- **[Nuclei](https://github.com/projectdiscovery/nuclei)** for template-based scanning.
-- **[SQLMap](https://github.com/sqlmapproject/sqlmap)** for the industry-standard SQLi detection.
-- **[Dirsearch](https://github.com/maurosoria/dirsearch)** for efficient path enumeration.
-- **[Arjun](https://github.com/s0md3v/Arjun)** for finding those hidden parameters.
+Special thanks to the open-source projects that power our orchestration:
+- **[Nuclei](https://github.com/projectdiscovery/nuclei)**
+- **[SQLMap](https://github.com/sqlmapproject/sqlmap)**
+- **[Dirsearch](https://github.com/maurosoria/dirsearch)**
+- **[Arjun](https://github.com/s0md3v/Arjun)**
 
 ---
-Built by SecNode. [Report an issue](https://github.com/SecNode/API-PENTESTER/issues).
+Built by SecNode. [Report an issue](https://github.com/SecNode/API-PENTESTER/issues).