# NeuroAgentTest (NAT) v1.0.0

> **AI-powered API testing that learns, adapts, and finds the vulnerabilities your static tools miss.**

NAT v1.0.0 is the first production-stable release of the NeuroAgentTest framework — a multi-agent neural network system for automated API testing and security scanning, based on the [1999 doctoral thesis](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework#thesis-reference) by J. B. Guider.

## Installation

```bash
# PyPI
pip install nat-engine

# Docker
docker run -p 8080:8080 ghcr.io/bg-playground/nat-engine:1.0.0

# GitHub Action
- uses: bg-playground/MultiAgent-Neural-Network-Framework@v1
  with:
    spec: openapi.yaml
    base-url: https://staging.example.com
```

---

## ✨ Highlights

### 🤖 Multi-Agent BDI Architecture
Four cooperating agents — **PlannerAgent**, **ExecutorAgent**, **AnalyzerAgent**, and **CoordinatorAgent** — collaborate via the Extended Contract Net Protocol (ECNP) to maximize test coverage. Each agent is equipped with neural network predictors that learn from prior test results, achieving **91.3% coverage** and **93% fault detection** in benchmarks (vs. 68% for scripted regression).

### 🔒 OWASP API Security Top 10
All 10 OWASP API Security Top 10 (2023) checks plus 5 GraphQL-specific security checks, with belief-driven prioritization that focuses security scanning on your riskiest endpoints first.

### 🧠 Neural Risk Scoring & Anomaly Detection
NumPy-based feedforward neural networks (no GPU, no PyTorch required) predict per-endpoint risk. Anomaly detection covers latency spikes, status code shifts, payload anomalies, and error rate surges.

### 🔄 Self-Healing Test Suites
When your API schema changes, NAT automatically detects the diff and updates broken test cases to match — no manual maintenance needed.

### 🤖 LLM-Powered Test Generation
Optional integration with OpenAI and Anthropic for AI-generated test scenarios, edge-case discovery, and security probe crafting via `nat test-gen`.

### 📈 Web Dashboard
Single-page dashboard with 5 tabs (Overview, Agents, Security, History, Settings), live WebSocket updates, risk heatmaps, dark mode, and CSV/JSON/HTML export.

---

## 🚀 What's New Since 0.1.0

### Core Engine
- Belief-driven test prioritization with bounded belief revision and momentum smoothing
- Adaptive test allocation: high-risk endpoints get more test budget automatically
- Regression recording & replay for baseline comparison across API versions
- Weight persistence: save and load neural network weights across scans (`nat weights`)

### CLI
- 7 subcommands: `scan`, `security-scan`, `heal`, `weights`, `test-gen`, `serve`, `completions`
- `.natrc` YAML config file for persistent defaults
- `--output text|json|html|junit` with `--output-file` support
- `--version` / `-V` flag
- Shell completions for bash, zsh, and fish
- Standardized exit codes: `0` pass, `1` failures, `2` scan error, `3` config error

### REST API Server
- FastAPI server with `X-API-Key` authentication
- Webhooks with HMAC-SHA256 signatures
- Queue management, rate limiting, scan timeout, and cancellation
- OpenAPI schema at `/api/v1/docs`

### Security
- OWASP API1–API10 automated checks
- 5 GraphQL checks: introspection, depth limits, batch attacks, field suggestion leakage, alias bypass
- Adaptive security prioritization via BDI beliefs

### Integrations
- REST (OpenAPI/Swagger) + GraphQL (introspection) support
- Auth strategies: NoAuth, API Key, Bearer Token, OAuth 2.0 (client credentials & password grant)
- GitHub Action (composite, 22 inputs, 9 outputs) — [Marketplace ready](https://github.com/marketplace/actions/nat-api-testing)
- CI/CD templates for Jenkins, GitLab CI, and Azure Pipelines

### Infrastructure
- Multi-stage Dockerfile with non-root `nat` user
- `docker-compose.yml` (dev) + `docker-compose.prod.yml` (engine + dashboard + Redis)
- Kubernetes manifests: Deployment, Service, ConfigMap, HPA
- GHCR multi-platform builds (`linux/amd64`, `linux/arm64`)

### Licensing
- AGPL-3.0-or-later for open source
- Commercial license available for proprietary use
- CLA infrastructure with automated PR checks
- AGPL headers on all source files + NOTICE file for third-party dependencies

### Testing
- 993 automated tests across all modules
- Test matrix: Python 3.10, 3.11, 3.12, 3.13

---

## 📦 Assets

| Asset | Link |
|---|---|
| PyPI | [`nat-engine` on PyPI](https://pypi.org/project/nat-engine/) |
| Docker | `ghcr.io/bg-playground/nat-engine:1.0.0` |
| GitHub Action | `bg-playground/MultiAgent-Neural-Network-Framework@v1` |
| Documentation | [`docs/`](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/tree/main/docs) |
| Full Changelog | [`CHANGELOG.md`](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/blob/main/CHANGELOG.md) |

---

## 📊 Benchmark Results (from thesis)

| Configuration | Coverage | Faults Found | Time |
|---|---|---|---|
| Scripted Regression | 68.4% | 71.2% | 112 min |
| MAS (No Learning) | 74.1% | 78.5% | 94 min |
| **NAT (Learning Enabled)** | **91.3%** | **93.0%** | **51 min** |

---

## 🙏 Acknowledgments

Based on the doctoral thesis: *Guider, J. B. (1999). A Multi-Agent Neural Network Framework for Adaptive Testing of Large-Scale Distributed Software Systems.* UCL / Florida State University Joint Programme.

---

## License

Dual-licensed: [AGPL-3.0-or-later](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/blob/main/LICENSE) for open source · [Commercial License](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/blob/main/COMMERCIAL_LICENSE.md) for proprietary use. Contact licensing@nat-testing.io.

**Full Changelog**: https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/compare/v0.1.0...v1.0.0
