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

Comparison vs. Competitors

Installation

pip (recommended):

pip install nat-engine

With optional extras:

# Browser functional testing + visual regression + accessibility + performance
pip install "nat-engine[browser]"

# gRPC scanning support
pip install "nat-engine[grpc]"

# All optional extras
pip install "nat-engine[browser,grpc,billing,observability]"

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
    output: allure           # also supports: ctrf, junit, html, json
    fail-if: "critical > 0 OR risk_score > 0.8"  # quality gate expression

gRPC scan

nat scan \
  --proto services/auth.proto \
  --grpc-endpoint grpc://localhost:50051 \
  --output json

Worker pool (parallel distributed execution)

# Launch a worker pool of 4 agents
nat worker launch --concurrency 4

# Check pool status
nat worker status

Export findings to an issue tracker

# List available exporters
nat export list

# Push findings to Jira
nat security-scan \
  --spec openapi.yaml \
  --base-url https://api.example.com \
  --export jira \
  --export-config jira_url=https://myco.atlassian.net \
  --export-config jira_project_key=SEC

Setup wizard and environment validation

# Interactive first-time setup
nat setup

# Validate your environment before a scan
nat doctor

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              │    │  GrpcSUT         │
│  (REST / OpenAPI)│    │  (GraphQL / introspect)  │    │  (.proto / gRPC) │
└──────────────────┘    └──────────────────────────┘    └──────────────────┘
         │
         ▼
┌───────────────────────────────────┐   ┌──────────────────────────────────┐
│  SecurityScanner                  │   │  FunctionalTestOrchestrator      │
│  OWASP API1–API10 + GRAPHQL 1–5  │   │  Visual Regression + A11y + Perf │
└───────────────────────────────────┘   └──────────────────────────────────┘

Documentation

The full documentation lives in docs/:

Project Structure

src/mannf/
├── core/
│   ├── agents/          # BDI agent implementations (Planner, Executor, Analyzer, Coordinator)
│   │   ├── worker_pool.py       # WorkerPool — parallel distributed test execution
│   │   └── autonomous_loop_agent.py  # Autonomous multi-iteration test loop
│   ├── anomaly/         # Enhanced anomaly detection (latency, status, payload, error rate)
│   ├── browser/         # Playwright-based functional testing engine
│   │   ├── functional_test_orchestrator.py  # Visual regression, accessibility, performance
│   │   └── security_scenario_generator.py
│   ├── prioritization/  # BeliefPrioritizer, RiskScorer, confidence calibration
│   └── validation/      # Self-validation runner
├── product/
│   ├── cli.py           # nat CLI (scan, security-scan, worker, export, setup, doctor, demo, …)
│   ├── server.py        # FastAPI REST API server with RBAC middleware
│   ├── dashboard/       # Web dashboard (risk heatmaps, belief charts, go-live status)
│   ├── exporters/       # 11 built-in exporters
│   │   ├── jira_exporter.py
│   │   ├── linear_exporter.py
│   │   ├── github_exporter.py
│   │   ├── gitlab_exporter.py
│   │   ├── azuredevops_exporter.py
│   │   ├── shortcut_exporter.py
│   │   ├── servicenow_exporter.py
│   │   ├── pagerduty_exporter.py
│   │   ├── webhook_exporter.py
│   │   ├── sentry_exporter.py
│   │   └── bugzilla_exporter.py
│   ├── ingestors/       # OpenAPI, GraphQL, gRPC (.proto), WebSocket, traffic (HAR/mitmproxy)
│   ├── integrations/    # HttpApiSUT, GraphQLSUT, GrpcSUT, WebSocketSUT, auth providers
│   ├── scheduling/      # Cron-based scheduled scans, JobQueue (in-memory/SQLite/Redis)
│   ├── billing/         # Stripe integration, plan tiers, tenant manager
│   ├── auth/            # OIDC/SAML SSO, RBAC middleware, audit logging
│   ├── formatters/      # Allure, CTRF, JUnit, HTML report formatters
│   └── middleware/      # Tenant isolation, audit middleware
action/              # GitHub Action entrypoint and result parser (PR annotations, quality gates)
action.yml           # Composite GitHub Action definition
scripts/
├── demo_orangehrm.py    # Live OrangeHRM E2E demo — login, CRUD, leave, recruitment
└── demo.sh / demo.bat   # Quick-start demo launchers
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
└── workflows/                # Example GitHub Actions workflows
docs/                         # Full documentation
├── guides/
│   ├── grpc-scanning.md      # gRPC scanning guide (proto parsing, TLS, RPC types)
│   └── demo-mode.md          # Demo mode walkthrough
└── demos/
    └── orangehrm.md          # OrangeHRM live demo guide

Requirements

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

Optional extras:

• [browser] — Playwright ≥ 1.40, Pillow ≥ 11 (functional testing, visual regression, accessibility, performance)
• [grpc] — grpcio-tools ≥ 1.60 (.proto file parsing for gRPC scanning)
• [billing] — stripe ≥ 8.0 (usage-based billing)
• [observability] — psutil ≥ 5.9 (system metrics)

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

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 licensing@nat-testing.io.

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