nat-engine 1.1.10

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

💡 Get notified on scan completion: Set up Slack alerts in seconds:

export NAT_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxx
nat security-scan --spec openapi.yaml --base-url https://api.example.com
# → NAT will POST a rich summary to your Slack channel when the scan finishes

See the Notifications Guide for Slack, Teams, and generic webhook setup.

---

Feature Highlights

Feature	Description
🤖 BDI Multi-Agent Engine	PlannerAgent, ExecutorAgent, AnalyzerAgent, and CoordinatorAgent collaborate via ECNP to maximize coverage
📐 REST + GraphQL + gRPC Testing	OpenAPI/Swagger, GraphQL introspection, and .proto-based gRPC scanning (unary, streaming, bidi) — no "coming soon"
🔒 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
🎯 Confidence Calibration	Per-finding confidence scores with calibration tuning and statistical confidence intervals
🔑 Flexible Auth	No auth, API key, Bearer token, OAuth 2.0 (client credentials & password grant), SSO (OIDC/SAML)
🏢 RBAC & Multi-Tenant	Role-based access control (admin/operator/viewer), SSO, tenant isolation, and audit logging
👷 Worker Pools	Parallel distributed test execution via nat worker launch — scale across multiple agents
📤 11 Exporters	Push findings to Jira, Linear, GitHub Issues, GitLab, Azure DevOps, Shortcut, ServiceNow, PagerDuty, Webhook, Sentry, and Bugzilla
🕐 Scheduled Scans	Cron-based recurring scan schedules — backend implemented, API surface in Phase 9.4
🌐 Functional Testing	Browser-based E2E test execution with DOM snapshots, screenshots, and interaction traces via Playwright
🖼️ Visual Regression	Pixel-diff analysis against stored baselines — catch unexpected UI changes automatically
♿ Accessibility Scanning	WCAG 2.1 compliance checks integrated into every browser-based scan
⚡ Performance Testing	Core Web Vitals measurement: LCP, FCP, TTI, CLS, TBT — every scan, every page
🐳 Docker-Ready	One-command server deployment; shared across the team
⚙️ CI/CD Integration	Native GitHub Actions support, Allure/CTRF export, PR annotations, and quality gates
🧙 Setup Wizard	nat setup interactive onboarding wizard and nat doctor pre-flight environment validation
🎬 Demo Mode	nat demo and scripts/demo_orangehrm.py for a live OrangeHRM E2E demo — no setup required
📈 Web Dashboard	Live risk heatmaps, belief visualization, anomaly timeline, and go-live status
🖥️ REST API Server	FastAPI server exposes all NAT capabilities as HTTP endpoints with RBAC and audit trail
🏅 Compliance Badges	nat badge generates shields.io-compatible OWASP, PCI-DSS, HIPAA, and SOC 2 pass/fail badges for README embedding

---

Comparison vs. Competitors

Capability	NAT	Postman	SoapUI	Burp Suite
OpenAPI spec scanning	✅	✅	✅	⚠️ limited
GraphQL support	✅	✅	❌	⚠️ limited
gRPC support	✅	❌	❌	❌
OWASP API Top 10	✅	❌	⚠️	✅
Adaptive AI prioritization	✅	❌	❌	❌
Risk scoring + anomaly detection	✅	❌	❌	❌
Confidence calibration	✅	❌	❌	❌
Browser functional testing	✅	❌	❌	❌
Visual regression testing	✅	❌	❌	❌
Accessibility scanning (WCAG)	✅	❌	❌	❌
Performance testing (Web Vitals)	✅	❌	❌	❌
Worker pools (parallel execution)	✅	❌	❌	❌
11 issue-tracker exporters	✅	❌	❌	⚠️ limited
Scheduled / recurring scans	✅	✅	❌	❌
RBAC + multi-tenant + SSO	✅	✅	❌	❌
OAuth 2.0 auth	✅	✅	✅	✅
CI/CD GitHub Action + quality gates	✅	✅	❌	❌
Allure / CTRF report export	✅	❌	❌	❌
Docker deployment	✅	❌	⚠️	❌
Open source (AGPL)	✅	❌	✅	❌
Programmatic Python API	✅	❌	❌	❌
Compliance badges (OWASP/PCI/HIPAA/SOC2)	✅	❌	❌	❌

---

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

Compliance badges

# Generate compliance badge markdown for README embedding
nat badge --format markdown

# Show OWASP API Top 10 badge only
nat badge --framework owasp-api-top10

# Export all badges as SVG files
nat badge --format svg --output-dir ./badges

Example shields.io badge output:

🏅 Compliance Badges

  OWASP API Top 10 2023:    9/10 passing  ✅
  PCI DSS 4.0:              7/7 passing   ✅
  HIPAA Security Rule:      6/6 passing   ✅
  SOC 2 Type II:            6/6 passing   ✅

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

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/
├── 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):

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