Update README.md to enhance project description and installation instructions

Author: Av7danger

README.md

@@ -1,69 +1,152 @@
 # SecNode API
 
-Schema-driven API security testing with LLM-assisted test generation and async execution.
+[![CI](https://github.com/secnode/secnodeapi/actions/workflows/secnode-pentest.yml/badge.svg)](https://github.com/secnode/secnodeapi/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)
 
-## What it does
+AI-augmented, schema-driven API penetration testing from OpenAPI/Swagger specs, with asynchronous execution and structured reporting.
 
-SecNode API ingests OpenAPI/Swagger specs, builds API context with an LLM, generates adversarial test cases, executes them concurrently, validates likely findings with deterministic retest, and writes reports.
+## Why SecNode API
 
-It is useful for:
+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.
 
-- fast staging API risk sweeps
-- CI security regression checks
-- structured test-case generation for manual review
+- Ingests local or remote OpenAPI/Swagger schema files
+- Uses an LLM to understand API behavior and generate adversarial test cases
+- Executes tests concurrently with optional proxy routing
+- Supports autonomous agent mode with request budgets and iterative replanning
+- Produces both human-readable and machine-readable findings
 
-## What it does not guarantee
+## What It Is and Is Not
 
-- no guarantee of zero false positives
-- no full replacement for manual penetration testing
-- no complete coverage of undocumented endpoints
+SecNode API is a practical automation layer for API security testing.
 
-## Quick start
+- It is useful for fast risk triage, regression checks, and structured analyst review
+- It does not replace manual penetration testing or threat modeling
+- It can still produce false positives or miss undocumented behavior
+
+## Installation
+
+### Requirements
+
+- Python 3.9+
+- Access to an LLM provider key (OpenAI or Anthropic)
+
+### Install from source
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 pip install -e .[dev]
+```
+
+On Windows (PowerShell):
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+pip install -e .[dev]
+```
+
+## Configuration
+
+Set the model and provider credentials before running scans:
 
+```bash
 export SECNODE_LLM="openai/gpt-4o"
 export OPENAI_API_KEY="your-api-key"
+```
 
-secnodeapi --target https://api.example.com/swagger.json
+Or with Anthropic:
+
+```bash
+export SECNODE_LLM="anthropic/claude-3-5-sonnet-20241022"
+export ANTHROPIC_API_KEY="your-anthropic-key"
 ```
 
-Reports are written to `results/<target>_<timestamp>/`.
+Provider keys are model-specific. See [LiteLLM providers](https://docs.litellm.ai/docs/providers).
+
+## Quick Start
+
+Run against a remote schema:
 
-## CLI usage
+```bash
+secnodeapi --target https://api.example.com/swagger.json
+```
+
+Run against a local schema file:
 
 ```bash
 secnodeapi --target ./openapi.yaml
-secnodeapi --target https://api.example.com/swagger.json --dry-run --dry-run-output results/tests.json
-secnodeapi --target https://api.example.com/swagger.json --auth-header "Authorization: Bearer token"
+```
+
+Reports are written to `results/<target_or_local_schema>_<timestamp>/`.
+
+## CLI Usage
+
+```bash
+secnodeapi --target ./openapi.yaml --schema-only
+secnodeapi --target https://api.example.com/swagger.json --dry-run --dry-run-output ./results/tests.json
+secnodeapi --target https://api.example.com/swagger.json --auth-header "Authorization: Bearer <token>"
 secnodeapi --target https://api.example.com/swagger.json --proxy http://127.0.0.1:8080 --insecure
+secnodeapi --target https://api.example.com/swagger.json --mode agent --request-budget 500 --max-iterations 6
 ```
 
-### Key flags
+### Key options
+
+- `--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
+- `--dry-run-output` write generated tests to JSON (requires `--dry-run`)
+- `--request-budget` max request count in agent mode
+- `--per-endpoint-budget` max attempts per endpoint in agent mode
+- `--max-iterations` max plan/execute loops in agent mode
+- `--proxy` route traffic via proxy
+- `--insecure` disable TLS verification for controlled environments
 
-- `--schema-only`: parse schema and output normalized structure
-- `--dry-run`: generate tests without executing
-- `--dry-run-output`: save generated tests to JSON
-- `--insecure`: disable TLS verification (controlled environments only)
+## Output
+
+Each run generates an output directory containing:
+
+- `report.md` with executive summary, severity overview, and evidence sections
+- `findings.json` for machine processing and pipeline integration
 
 ## Development
 
-- `make install-dev`
-- `make lint`
-- `make test`
-- `make build`
+```bash
+make install-dev
+make lint
+make test
+make test-cov
+make build
+```
+
+## CI
+
+GitHub Actions workflow runs:
+
+- lint checks
+- test suite with coverage thresholds
+- package build
+- scan job template for staging targets
+
+## Security and Responsible Use
+
+Only test systems you own or are explicitly authorized to assess.
+
+- Read the disclosure process in [SECURITY.md](./SECURITY.md)
+- Follow community expectations in [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
 
-See:
+## Contributing
 
-- `docs/ARCHITECTURE.md`
-- `docs/DEVELOPMENT.md`
-- `docs/API_REFERENCE.md`
-- `docs/SECURITY.md`
+Contributions are welcome. For setup and PR expectations, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License
 
-Apache 2.0. See `LICENSE`.
+Apache 2.0. See [LICENSE](./LICENSE).