Metadata-Version: 2.4
Name: nat-engine
Version: 1.0.5
Summary: NeuroAgentTest (NAT) — AI-powered API testing with multi-agent neural networks, OWASP security scanning, and adaptive test allocation
Author-email: NAT Contributors <licensing@nat-testing.io>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/bg-playground/MultiAgent-Neural-Network-Framework
Project-URL: Documentation, https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/tree/main/docs
Project-URL: Repository, https://github.com/bg-playground/MultiAgent-Neural-Network-Framework
Project-URL: Issues, https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/issues
Project-URL: Changelog, https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/blob/main/CHANGELOG.md
Keywords: api-testing,security-scanning,owasp,neural-network,multi-agent,bdi,testing,quality-assurance,openapi,graphql
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Security
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.24
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.34
Requires-Dist: python-multipart>=0.0.18
Requires-Dist: opentelemetry-api>=1.20
Requires-Dist: azure-monitor-opentelemetry>=1.6
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Dist: asyncpg>=0.29
Requires-Dist: alembic>=1.13
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-timeout>=2.1; extra == "dev"
Requires-Dist: respx>=0.22; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: stripe>=8.0; extra == "dev"
Requires-Dist: Pillow>=11.0; extra == "dev"
Provides-Extra: billing
Requires-Dist: stripe>=8.0; extra == "billing"
Provides-Extra: azure-storage
Requires-Dist: azure-storage-blob>=12.19; extra == "azure-storage"
Provides-Extra: observability
Requires-Dist: psutil>=5.9; extra == "observability"
Provides-Extra: browser
Requires-Dist: playwright>=1.40.0; extra == "browser"
Requires-Dist: Pillow>=11.0; extra == "browser"
Dynamic: license-file

# NeuroAgentTest (NAT)

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

[![PyPI](https://img.shields.io/pypi/v/nat-engine)](https://pypi.org/project/nat-engine/)
[![Python](https://img.shields.io/pypi/pyversions/nat-engine)](https://pypi.org/project/nat-engine/)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/blob/main/LICENSE)
[![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?logo=docker)](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/pkgs/container/nat-engine)

NAT is an open-source, **multi-agent neural network framework** for automated API testing and security scanning. Powered by BDI (Belief-Desire-Intention) agents and the Extended Contract Net Protocol (ECNP), NAT continuously learns from test results to focus coverage where risk is highest — so your team ships faster with fewer surprises.

---

## 🎯 Demo Mode

See NAT in action with a single command:

```bash
nat demo
# or with Docker:
docker run -p 8080:8080 ghcr.io/bg-playground/nat-engine:demo
```

The dashboard opens automatically with live agent activity, risk heatmaps, security findings, and more. Works offline — perfect for sales demos and conferences.

👉 [Full demo guide](docs/guides/demo-mode.md)

---

## 📸 Dashboard Preview

NAT's web dashboard gives you full visibility into scan results, agent activity, and security findings.

### Risk Overview & Anomaly Detection
![Dashboard Overview](docs/assets/dashboard-overview-top.png)
> The Overview tab shows total scans, endpoints discovered, pass/fail rates, health score, and a real-time anomaly feed — all at a glance.

### Multi-Agent Activity
![Agent Activity](docs/assets/dashboard-agents-dark.png)
> Watch BDI agents (Planner, Executor, Analyzer, Coordinator) reason about uncertainty and update their beliefs as they learn from each test result.

### OWASP Security Findings
![Security Findings](docs/assets/dashboard-security.png)
> Automated OWASP API Security Top 10 checks with severity breakdown, confidence scores, and actionable remediation guidance.

### Security Finding Detail
![Security Detail](docs/assets/dashboard-security-detail.png)
> Drill into any finding to see evidence, CWE mapping, and specific remediation steps.

---

## 30-Second Quickstart

```bash
# 1. Install
pip install nat-engine

# 2. Scan an API
nat scan \
  --spec examples/petstore-openapi.yaml \
  --base-url https://petstore3.swagger.io/api/v3

# 3. Security audit
nat security-scan \
  --spec examples/petstore-openapi.yaml \
  --base-url https://petstore3.swagger.io/api/v3
```

That's it — NAT parses your OpenAPI spec, distributes test tasks across its agent network, scores risk, and reports findings. Full docs at [`docs/`](docs/README.md).

---

## Feature Highlights

| Feature | Description |
|---|---|
| 🤖 **BDI Multi-Agent Engine** | PlannerAgent, ExecutorAgent, AnalyzerAgent, and CoordinatorAgent collaborate via ECNP to maximize coverage |
| 📐 **REST + GraphQL Testing** | OpenAPI/Swagger spec scanning and GraphQL introspection-based discovery |
| 🔒 **OWASP API Top 10** | 10 automated security checks (BOLA, Broken Auth, Mass Assignment, SSRF, and more) + 5 GraphQL-specific checks |
| 🧠 **Belief-Driven Prioritization** | Neural networks predict which endpoints are highest risk and allocate test budget accordingly |
| 📊 **Risk Scoring + Anomaly Detection** | Continuous scoring with latency spike, status-shift, and error-rate anomaly alerts |
| 🔑 **Flexible Auth** | No auth, API key, Bearer token, OAuth 2.0 (client credentials & password grant) |
| 🐳 **Docker-Ready** | One-command server deployment; shared across the team |
| ⚙️ **GitHub Action** | Drop-in CI/CD integration — block PRs on high-severity findings |
| 📈 **Web Dashboard** | Live risk heatmaps, belief visualization, anomaly timeline |
| 🖥️ **REST API Server** | FastAPI server exposes all NAT capabilities as HTTP endpoints |

---

## Comparison vs. Competitors

| Capability | NAT | Postman | SoapUI | Burp Suite |
|---|---|---|---|---|
| OpenAPI spec scanning | ✅ | ✅ | ✅ | ⚠️ limited |
| GraphQL support | ✅ | ✅ | ❌ | ⚠️ limited |
| OWASP API Top 10 | ✅ | ❌ | ⚠️ | ✅ |
| Adaptive AI prioritization | ✅ | ❌ | ❌ | ❌ |
| Risk scoring + anomaly detection | ✅ | ❌ | ❌ | ❌ |
| OAuth 2.0 auth | ✅ | ✅ | ✅ | ✅ |
| CI/CD GitHub Action | ✅ | ✅ | ❌ | ❌ |
| Docker deployment | ✅ | ❌ | ⚠️ | ❌ |
| Open source (AGPL) | ✅ | ❌ | ✅ | ❌ |
| Programmatic Python API | ✅ | ❌ | ❌ | ❌ |

---

## Installation

**pip (recommended):**
```bash
pip install nat-engine
```

**Docker:**
```bash
docker run -p 8080:8080 ghcr.io/bg-playground/nat-engine:latest
```

**From source:**
```bash
git clone https://github.com/bg-playground/MultiAgent-Neural-Network-Framework.git
cd MultiAgent-Neural-Network-Framework
pip install -e ".[dev]"
```

See [`docs/getting-started/installation.md`](docs/getting-started/installation.md) for full details.

### Configuration

Copy the example environment file and customize it:

```bash
cp .env.example .env
# Edit .env with your settings
```

See [`.env.example`](.env.example) for all available configuration options, including database, authentication, rate limiting, webhooks, LLM integration, and exporter settings.

> **Note:** If `DATABASE_URL` is not set, NAT runs in in-memory mode and all scan data is lost on restart. Set `DATABASE_URL` to a PostgreSQL connection string for persistent storage.

---

## Usage Examples

### REST API scan

```bash
nat scan \
  --spec openapi.yaml \
  --base-url https://api.example.com \
  --auth-token $API_TOKEN \
  --output json
```

### GraphQL scan

```bash
nat scan \
  --type graphql \
  --base-url https://api.example.com/graphql \
  --graphql-introspection
```

### OWASP security audit

```bash
nat security-scan \
  --spec openapi.yaml \
  --base-url https://api.example.com \
  --severity-threshold high \
  --output markdown
```

### OAuth 2.0 authenticated scan

```bash
nat scan \
  --spec openapi.yaml \
  --base-url https://api.example.com \
  --oauth2-token-url https://auth.example.com/oauth/token \
  --oauth2-client-id $CLIENT_ID \
  --oauth2-client-secret $CLIENT_SECRET
```

### GitHub Actions integration

```yaml
- uses: bg-playground/MultiAgent-Neural-Network-Framework@main
  with:
    spec: openapi.yaml
    base-url: https://staging.example.com
    security-scan: 'true'
    fail-on-severity: high
```

### Programmatic Python API

```python
import asyncio
from mannf.integrations.http_sut import HttpApiSUT
from mannf.integrations.openapi_parser import OpenApiParser
from mannf.integrations.auth import BearerTokenAuth
from mannf.testing.models import TestSuite

async def main():
    auth = BearerTokenAuth("my-token")
    sut = HttpApiSUT(base_url="https://api.example.com", auth=auth)
    parser = OpenApiParser(spec_path="openapi.yaml", base_url="https://api.example.com",
                           registry=sut.registry)
    test_cases = parser.parse()

    suite = TestSuite(name="My API")
    for tc in test_cases:
        suite.add_case(tc)
        result = await sut.execute(tc)
        suite.record_result(result)

    s = suite.summary()
    print(f"Passed: {s['passed']}/{s['total']} ({s['pass_rate']*100:.1f}%)")

asyncio.run(main())
```

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        NATOrchestrator                          │
│                                                                 │
│  ┌───────────────┐  TASK_ANNOUNCEMENT  ┌──────────────────────┐│
│  │ PlannerAgent  │────────────────────▶│ CoordinatorAgent     ││
│  │               │                    │                      ││
│  │ Predictor NN  │◀── CONTRACT_RESULT ─│ ECNP bid collection  ││
│  │ BeliefState   │                    │ + award logic        ││
│  └───────────────┘                    └──────────┬───────────┘│
│                                                  │             │
│                               CONTRACT_AWARD     │             │
│                                                  ▼             │
│                                     ┌─────────────────────┐   │
│                                     │ ExecutorAgent (×N)  │   │
│                                     │                     │   │
│                                     │ Oracle NN + BDI     │   │
│                                     │ Bids on tasks       │   │
│                                     └──────────┬──────────┘   │
│                                                │               │
│                           TEST_RESULT /        │               │
│                           CONTRACT_RESULT      │               │
│                                                ▼               │
│  ┌───────────────┐◀─ BELIEF_UPDATE ── ┌─────────────────────┐ │
│  │ PlannerAgent  │                    │ AnalyzerAgent (×M)  │ │
│  │ (belief sync) │                    │                     │ │
│  └───────────────┘                    │ Autoencoder NN      │ │
│                                       │ Anomaly detection   │ │
│                                       │ BeliefState update  │ │
│                                       └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
         │ async pub/sub Message Bus │
         ▼                           ▼
┌──────────────────┐    ┌──────────────────────────┐
│  HttpApiSUT      │    │  GraphQLSUT              │
│  (REST / OpenAPI)│    │  (GraphQL / introspect)  │
└──────────────────┘    └──────────────────────────┘
         │
         ▼
┌───────────────────────────────────┐
│  SecurityScanner                  │
│  OWASP API1–API10 + GRAPHQL 1–5  │
└───────────────────────────────────┘
```

---

## Documentation

The full documentation lives in [`docs/`](docs/README.md):

| Section | Contents |
|---|---|
| [Getting Started](docs/getting-started/quickstart.md) | Install and first scan |
| [Guides](docs/guides/cli-reference.md) | CLI, REST API, Docker, CI/CD, Dashboard |
| [API Reference](docs/api-reference/rest-api.md) | REST endpoints, Python API, GitHub Action |
| [How-To](docs/how-to/run-security-audit.md) | Step-by-step task recipes |
| [Concepts](docs/concepts/architecture.md) | Architecture, BDI agents, neural networks |
| [Troubleshooting](docs/troubleshooting/common-issues.md) | Common problems and solutions |
| [FAQ](docs/faq.md) | Frequently asked questions |
| [Changelog](docs/changelog.md) | Release history |
| [Contributing](docs/contributing.md) | How to contribute |

---

## Project Structure

```
src/mannf/
├── agents/          # BDI agent implementations (Planner, Executor, Analyzer, Coordinator)
├── anomaly/         # Enhanced anomaly detection (latency, status, payload, error rate)
├── dashboard/       # Web dashboard (FastAPI + WebSocket, risk heatmaps, belief charts)
├── distributed/     # Endpoint registry and SUT interface
├── integrations/
│   ├── auth.py      # NoAuth, ApiKeyAuth, BearerTokenAuth, OAuth2Auth
│   ├── http_sut.py  # HttpApiSUT — real HTTP API testing via httpx
│   ├── graphql_sut.py      # GraphQLSUT — introspection + query/mutation execution
│   ├── graphql_parser.py   # GraphQL schema parser and test case generator
│   └── openapi_parser.py   # OpenAPI/Swagger parser → test cases
├── messaging/       # Async pub/sub message bus + ECNP message types
├── neural/          # NumPy MLP with backpropagation (no GPU required)
├── prioritization/  # BeliefPrioritizer, RiskScorer, AdaptiveController
├── security/        # SecurityScanner, OWASP checks, SecurityReporter
├── testing/         # TestCase, TestResult, TestSuite, adaptive controller
├── cli.py           # nat scan + nat security-scan CLI
└── server.py        # FastAPI REST API server

action/              # GitHub Action entrypoint and result parser
action.yml           # Composite GitHub Action definition
Dockerfile           # Multi-stage production image
docker-compose.yml   # Local development Compose file
examples/
├── petstore-openapi.yaml     # Sample OpenAPI spec
├── graphql-schema.graphql    # Sample GraphQL schema
├── python/                   # Programmatic usage examples
│   ├── basic_scan.py
│   ├── graphql_scan.py
│   ├── security_audit.py
│   └── oauth2_scan.py
└── workflows/                # Example GitHub Actions workflows
docs/                         # Full documentation
```

---

## Requirements

- Python ≥ 3.10
- NumPy ≥ 1.24
- No GPU, no PyTorch, no external ML dependencies

---

## 🚀 Deployment

NAT runs on Azure Container Apps with automatic scaling and managed TLS.

- **Setup guide:** [`deploy/azure/README.md`](deploy/azure/README.md) — complete step-by-step instructions
- **One-command setup:** `cd deploy/azure && ./setup.sh` — idempotent bootstrap script
- **Custom domain:** `cd deploy/azure && ./custom-domain.sh` — configure `api.nat-testing.io`
- **CI/CD pipeline:** Push to `main` → Docker build → GHCR push → ACA deploy → health check

---

## Thesis Reference

> Guider, J. B. (1999). *A Multi-Agent Neural Network Framework for Adaptive
> Testing of Large-Scale Distributed Software Systems*. Doctoral dissertation,
> UCL / Florida State University Joint Programme.

Key results from the original thesis (Chapter 6, Table 6.1):

| 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** |

---

## License

NeuroAgentTest (NAT) is dual-licensed:

- **[AGPL-3.0-or-later](LICENSE)** — for open-source projects, academic research, and personal use.
- **[Commercial License](COMMERCIAL_LICENSE.md)** — for proprietary products and SaaS deployments where AGPL-3.0 copyleft obligations are not acceptable.

For commercial licensing inquiries, contact **licensing@nat-testing.io**.

All contributors must agree to the [Contributor License Agreement (CLA)](CLA.md).

See [docs/faq.md](docs/faq.md#licensing--community) for licensing FAQs, including information on internal use, CI/CD pipelines, and the CLA.

A `NOTICE` file listing all third-party dependency licenses is included in the repository root ([NOTICE](NOTICE)).
