nat-engine 1.0.5

NeuroAgentTest (NAT) — AI-powered API testing with multi-agent neural networks, OWASP security scanning, and adaptive test allocation

NeuroAgentTest (NAT)

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

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:

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

---

📸 Dashboard Preview

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

Risk Overview & Anomaly Detection

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

Watch BDI agents (Planner, Executor, Analyzer, Coordinator) reason about uncertainty and update their beliefs as they learn from each test result.

OWASP Security Findings

Automated OWASP API Security Top 10 checks with severity breakdown, confidence scores, and actionable remediation guidance.

Security Finding Detail

Drill into any finding to see evidence, CWE mapping, and specific remediation steps.

---

30-Second Quickstart

# 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/.

---

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):

pip install nat-engine

Docker:

docker run -p 8080:8080 ghcr.io/bg-playground/nat-engine:latest

From source:

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 for full details.

Configuration

Copy the example environment file and customize it:

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

See .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

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

GraphQL scan

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

OWASP security audit

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

OAuth 2.0 authenticated scan

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

- 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

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/:

Section	Contents
Getting Started	Install and first scan
Guides	CLI, REST API, Docker, CI/CD, Dashboard
API Reference	REST endpoints, Python API, GitHub Action
How-To	Step-by-step task recipes
Concepts	Architecture, BDI agents, neural networks
Troubleshooting	Common problems and solutions
FAQ	Frequently asked questions
Changelog	Release history
Contributing	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 — 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 — for open-source projects, academic research, and personal use.
• Commercial License — for proprietary products and SaaS deployments where AGPL-3.0 copyleft obligations are not acceptable.

For commercial licensing inquiries, contact [e-mail].

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

See docs/faq.md 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).