docs: Add example README

Author: vishnurajkv

examples/README.md

@@ -1,9 +1,183 @@
-# Examples
+# SecNode API
 
-This directory contains usage examples and sample schema-driven scan flows.
+[![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)
 
-Example command:
+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
+- 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 Is and Is Not
+
+SecNode API is a practical automation layer for API security testing.
+
+- 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]
+```
+
+### Install with uv (recommended)
+
+```bash
+uv sync --extra dev
+```
+
+On Windows (PowerShell):
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+pip install -e .[dev]
+```
+
+On Windows (PowerShell) with uv:
+
+```powershell
+uv sync --extra 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"
+```
+
+Or with Anthropic:
 
 ```bash
-secnodeapi --target ./examples/openapi.yaml --dry-run --dry-run-output ./results/tests.json
+export SECNODE_LLM="anthropic/claude-3-5-sonnet-20241022"
+export ANTHROPIC_API_KEY="your-anthropic-key"
 ```
+
+Or with Ollama:
+
+```bash
+export SECNODE_LLM="ollama/llama3.1"
+export OLLAMA_API_BASE="http://localhost:11434" # optional, defaults to localhost if omitted
+```
+
+Provider credentials are model-specific. `openai/*` requires `OPENAI_API_KEY`, `anthropic/*`
+requires `ANTHROPIC_API_KEY`, and `ollama/*` can run locally without cloud API keys.
+See [LiteLLM providers](https://docs.litellm.ai/docs/providers).
+
+## Quick Start
+
+Run against a remote schema:
+
+```bash
+secnodeapi --target https://api.example.com/swagger.json
+```
+
+Run against a local schema file:
+
+```bash
+secnodeapi --target ./openapi.yaml
+```
+
+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 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
+
+## 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
+
+```bash
+make install-dev
+make lint
+make test
+make test-cov
+make build
+```
+
+Using uv-native targets:
+
+```bash
+make install-dev-uv
+make lint-uv
+make test-uv
+make test-cov-uv
+make build-uv
+```
+
+## 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)
+
+## Contributing
+
+Contributions are welcome. For setup and PR expectations, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+Apache 2.0. See [LICENSE](./LICENSE).