nat-engine 1.0.5__tar.gz

nat_engine-1.0.5/.dockerignore

@@ -0,0 +1,44 @@
+# .dockerignore — exclude files not needed in the Docker build context
+
+# Python cache and build artefacts
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Development / test files
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+*.log
+
+# Version control
+.git/
+.gitignore
+
+# Editor/IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Documentation and non-essential assets
+1999_Doctoral_Thesis_Brad_Guider_DRAFT.docx
+InitialResearch.md
+
+# Docker files (avoid recursive context)
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# Test files (not needed at runtime)
+tests/
+examples/

nat_engine-1.0.5/CHANGELOG.md

@@ -0,0 +1,179 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+_Nothing yet._
+
+---
+
+## [1.0.0] — 2026-03-22
+
+### Added
+
+#### Multi-Agent BDI Architecture
+- `PlannerAgent` — generates and reorders test plans based on belief state; produces ECNP call-for-proposals.
+- `ExecutorAgent` — executes individual test tasks; submits ECNP bids; records results back to the `BeliefState`.
+- `AnalyzerAgent` — consumes raw results; runs anomaly detection; updates belief scores.
+- `CoordinatorAgent` — orchestrates the full scan lifecycle; manages agent pool and task dispatch.
+- `NATOrchestrator` — top-level orchestrator that wires together all agents and coordinates the scan lifecycle.
+- `BeliefState` — thread-safe key-value store for per-endpoint agent beliefs (error rates, latency profiles, anomaly flags).
+- `BeliefPrioritizer` — scores pending operations using belief state; returns an ordered list for the `PlannerAgent`.
+
+#### ECNP Protocol
+- `ECNPMessage`, `ECNPCallForProposal`, `ECNPBid`, `ECNPAward` message types.
+- `ECNPBroker` — routes messages between agents with priority queuing.
+- Enables concurrent multi-worker test execution with minimal coordination overhead.
+
+#### Neural Network Oracles
+- `NeuralNetwork` — NumPy-based feedforward neural network with Xavier weight initialization, sigmoid/ReLU activations, mini-batch gradient descent, and backpropagation.
+- `RiskScorer` — combines security-finding penalties, anomaly signals, and pass-rate into a composite score in `[0.0, 1.0]`.
+- Neural oracle per endpoint that predicts risk level and guides adaptive test allocation.
+
+#### Adaptive Test Allocation
+- `TestCaseGenerator` — produces boundary-value, null-field, type-mismatch, and happy-path test cases from operation schemas.
+- Adaptive budget allocation: high-belief-risk endpoints receive more test cases; low-risk endpoints are sampled.
+- Belief-driven prioritization integrates security findings, anomaly counts, and historical pass rates.
+
+#### Security Scanning (OWASP API Top 10)
+- All 10 OWASP API Security Top 10 (2023) checks:
+  - `API1` — Broken Object Level Authorization (BOLA/IDOR)
+  - `API2` — Broken Authentication
+  - `API3` — Broken Object Property Level Authorization (mass assignment)
+  - `API4` — Unrestricted Resource Consumption (rate limiting)
+  - `API5` — Broken Function Level Authorization
+  - `API6` — Unrestricted Access to Sensitive Business Flows
+  - `API7` — Server Side Request Forgery (SSRF)
+  - `API8` — Security Misconfiguration
+  - `API9` — Improper Inventory Management
+  - `API10` — Unsafe Consumption of APIs
+- 5 GraphQL-specific security checks (GRAPHQL-1 through GRAPHQL-5): introspection, depth limits, batch attacks, field suggestion leakage, alias-based rate-limit bypass.
+- `SecurityCheck` base class for custom check plugins.
+- Adaptive security prioritization: `prioritize_for_security()` scores endpoints by risk and belief state.
+
+#### LLM-Powered Test Generation
+- `LLMProvider` ABC with `OpenAIProvider` and `AnthropicProvider` implementations.
+- `LLMConfig` and `get_provider()` factory for easy initialization.
+- Prompt templates for test scenario generation, edge-case discovery, and security probe crafting.
+- CLI: `--use-llm`, `--llm-provider`, `--llm-model`, `--llm-api-key` flags; `nat test-gen` subcommand.
+- Server: `POST /api/v1/llm/generate` endpoint.
+
+#### CLI — All Subcommands
+- `nat scan` — run adaptive functional tests against an OpenAPI/Swagger or GraphQL spec.
+- `nat security-scan` — run OWASP and GraphQL security checks.
+- `nat heal` — generate a healing report from spec diff (`--old-spec`, `--new-spec`).
+- `nat weights` — list, save, and inspect named weight snapshots.
+- `nat test-gen` — LLM-powered test generation from a spec.
+- `nat serve` — start the NAT REST API server.
+- `nat completions bash|zsh|fish` — generate shell completion scripts.
+- `.natrc` YAML config file for persistent defaults (`base_url`, `spec`, `output`, etc.).
+- `--output text|json|html|junit` and `--output-file` for flexible reporting.
+- Exit codes: `0` = all tests passed, `1` = test failures, `2` = scan error, `3` = config error.
+
+#### REST API Server
+- FastAPI-based server with all NAT capabilities exposed as HTTP endpoints.
+- `X-API-Key` authentication (configured via `NAT_API_KEY` environment variable).
+- Webhooks with HMAC-SHA256 signatures (`webhook_url`, `webhook_secret`, `webhook_headers`).
+- Queue management: `NAT_MAX_CONCURRENT_SCANS`, `NAT_MAX_QUEUE_DEPTH`, `GET /api/v1/queue`.
+- Rate limiting (`NAT_RATE_LIMIT`, e.g. `100/minute`).
+- Scan timeout (`NAT_SCAN_TIMEOUT`).
+- `DELETE /api/v1/scan/{id}` for scan cancellation.
+- Structured error responses: `{"error": {"code", "message", "details"}}`.
+- OpenAPI schema at `/api/v1/openapi.json`, Swagger UI at `/api/v1/docs`, ReDoc at `/api/v1/redoc`.
+- `ScanStatus` values: `QUEUED`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`, `TIMED_OUT`.
+
+#### Web Dashboard
+- Single-page dashboard with 5 tabs: Overview, Agents, Security, History, Settings.
+- Summary cards: total scans, pass rate, active agents, open findings.
+- Live scan queue with real-time WebSocket updates.
+- Export: HTML, JSON, and CSV report formats.
+- Settings tab: view server/auth/queue/webhook configuration.
+- Scan history with comparison across runs.
+- Dark mode and fully responsive layout.
+- `GET /api/v1/dashboard/settings` — server configuration introspection endpoint.
+- `GET /api/v1/scan/{id}/export?format=html|json|csv` — on-demand report export.
+
+#### Docker / Compose / Kubernetes
+- Multi-stage `Dockerfile`: builder stage installs deps and builds wheel; final stage uses `python:3.11-slim`.
+- Multi-platform builds: `linux/amd64` and `linux/arm64`.
+- `docker-compose.yml` — single-service deployment; `docker-compose.prod.yml` — engine + dashboard + Redis.
+- Kubernetes manifests in `deploy/k8s/`: Deployment, Service, ConfigMap, HPA.
+- GHCR publish workflow (`.github/workflows/docker-publish.yml`).
+- Non-root runtime user `nat` (UID 1000); `HEALTHCHECK` against `GET /health`.
+
+#### GitHub Action + CI/CD Templates
+- `action.yml` — composite GitHub Action, marketplace-ready with 22 inputs and 9 outputs.
+- Docker-based Action variant for faster startup in self-hosted runners.
+- `.github/workflows/action-release.yml` — automated GitHub Marketplace release with major version tag tracking.
+- Jenkins shared library (`ci-templates/jenkins/`): `natScan()` pipeline step, Jenkinsfile examples.
+- GitLab CI template (`ci-templates/gitlab/.gitlab-ci-nat.yml`) with MR pipeline support and JUnit artifact upload.
+- Azure Pipelines template (`ci-templates/azure/azure-pipelines-nat.yml`) with `PublishTestResults@2`.
+- Example workflows for security gates, scheduled nightly scans, and matrix strategies.
+
+#### AGPL-3.0 Dual-License
+- `LICENSE` — GNU Affero General Public License v3.0.
+- `COMMERCIAL_LICENSE.md` — enterprise commercial license terms with AGPL vs. commercial comparison.
+- `CLA.md` — Individual and Corporate Contributor License Agreements.
+- `CLA_SIGNATORIES.md` — signed CLA tracking file.
+- `.github/workflows/cla.yml` — automated CLA check on pull requests.
+- AGPL-3.0 license headers on all Python source files.
+- `NOTICE` — third-party dependency license notices.
+
+#### Self-Healing Test Suites
+- `SchemaDiffer` and `GraphQLSchemaDiffer` — compute structural diffs between spec versions.
+- `TestHealer` — automatically updates broken test cases to match new schema.
+- `HealingReport` with per-endpoint patch summaries.
+- CLI: `nat heal --old-spec`/`--new-spec`; server: `POST/GET /api/v1/heal`.
+
+#### Regression Recording & Replay
+- `RegressionRecorder` — captures request/response pairs during a scan.
+- `RegressionReplayer` — replays a baseline recording against the live API.
+- `RegressionDiffer` — diffs current vs. baseline recordings with configurable masking.
+- CLI: `--record-regression FILE`, `--replay FILE`, `--regression-diff-only`, `--mask-sensitive`.
+- Server: `POST/GET /api/v1/regression/{record,replay,diff,baselines}`.
+
+#### Weight Persistence
+- `WeightStore` — JSON-based save/load for neural network weights.
+- `WeightRegistry` — named snapshot management with metadata.
+- CLI: `nat scan --save-weights`, `--load-weights`, `--weights-dir`; `nat weights list/save/info`.
+- Server: `POST/GET/DELETE /api/v1/weights/`.
+
+#### Authentication Strategies
+- `NoAuth`, `ApiKeyAuth`, `BearerTokenAuth`, `OAuth2Auth` (client_credentials + password grant).
+- All strategies implement the `AuthStrategy` interface for pluggable composition.
+
+#### Testing Infrastructure
+- 993 automated tests covering all modules.
+- Test matrix: Python 3.10, 3.11, 3.12, 3.13.
+- `pytest-asyncio` for async test support; `respx` for HTTP mocking.
+
+---
+
+## [0.1.0] — Initial Release
+
+### Added
+
+- Initial multi-agent BDI framework with `PlannerAgent`, `ExecutorAgent`, `AnalyzerAgent`, `CoordinatorAgent`.
+- `NeuralNetwork` — NumPy-based feedforward network with backpropagation.
+- ECNP protocol for agent coordination.
+- `BeliefState` and `BeliefPrioritizer`.
+- `OpenAPIParser` and `TestCaseGenerator` for REST API testing.
+- `GraphQLParser` and `GraphQLSUT` for GraphQL testing.
+- OWASP API Top 10 and GraphQL security checks.
+- `nat scan` and `nat security-scan` CLI subcommands.
+- FastAPI REST server (`nat-server`).
+- Basic web dashboard.
+- `Dockerfile` and `docker-compose.yml`.
+- `action.yml` — composite GitHub Action.
+
+---
+
+[Unreleased]: https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/releases/tag/v0.1.0

nat_engine-1.0.5/CLA.md

@@ -0,0 +1,114 @@
+# Contributor License Agreement (CLA)
+
+**NeuroAgentTest (NAT) — Multi-Agent Neural Network Framework**
+
+Thank you for your interest in contributing to NeuroAgentTest (NAT). This
+Contributor License Agreement ("Agreement") clarifies the intellectual
+property rights granted with contributions to this project.
+
+By submitting a contribution (a pull request, patch, or any other material)
+to this repository, you agree to the following terms:
+
+---
+
+## 1. Definitions
+
+- **"You"** means the individual or legal entity submitting a contribution.
+- **"Contribution"** means any original work of authorship, including any
+  modifications or additions to existing work, submitted to this project.
+- **"Project"** means the NeuroAgentTest (NAT) software and associated
+  documentation hosted at
+  [https://github.com/bg-playground/MultiAgent-Neural-Network-Framework](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework).
+- **"Maintainers"** means the current maintainers and copyright holders of
+  the Project.
+
+---
+
+## 2. Grant of Copyright License
+
+You hereby grant to the Maintainers and to all recipients of software
+distributed by the Project a **perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable** copyright license to reproduce,
+prepare derivative works of, publicly display, publicly perform,
+sublicense, and distribute your Contributions and such derivative works.
+
+---
+
+## 3. Grant of Patent License
+
+You hereby grant to the Maintainers and to all recipients of software
+distributed by the Project a **perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable** (except as stated in this section)
+patent license to make, have made, use, offer to sell, sell, import, and
+otherwise transfer the Project, where such license applies only to those
+patent claims licensable by you that are necessarily infringed by your
+Contribution(s) alone or by combination of your Contribution(s) with the
+Project.
+
+---
+
+## 4. Right to Re-License
+
+You grant the Maintainers the right to re-license your Contributions,
+including under a proprietary or commercial license, as part of the
+Project's dual-licensing model (AGPL-3.0 and Commercial License). This
+allows the Maintainers to offer commercial licenses to third parties
+without violating your rights or the open-source license.
+
+---
+
+## 5. Copyright Assignment
+
+To the extent permitted by applicable law and as necessary to support the
+dual-licensing model, you assign to the Maintainers all right, title, and
+interest in your Contributions, including all copyright and related rights.
+Where assignment is not permitted by law, you grant the broadest possible
+license as described in Sections 2 and 3.
+
+---
+
+## 6. Representations
+
+You represent that:
+
+1. **Original work**: Each Contribution is your original creation, or you
+   have sufficient rights to submit it under this Agreement.
+2. **No third-party restrictions**: Your Contribution does not include any
+   material that is subject to third-party intellectual property rights
+   (patents, copyrights, trade secrets) that would restrict the Maintainers'
+   ability to use, distribute, or re-license the Contribution.
+3. **Employment**: If your employer has rights to intellectual property you
+   create, you have received permission to make the Contribution on behalf
+   of your employer, or your employer has waived such rights.
+4. **Accuracy**: You agree to notify the Maintainers if any of these
+   representations become inaccurate.
+
+---
+
+## 7. No Obligation
+
+Nothing in this Agreement obligates the Maintainers to accept, include, or
+use your Contribution. Acceptance of this Agreement does not guarantee that
+your Contribution will be merged.
+
+---
+
+## 8. How to Indicate Acceptance
+
+By opening a pull request or submitting a patch to this repository, you
+indicate that you have read, understood, and agree to the terms of this
+Contributor License Agreement.
+
+If you are contributing on behalf of an organization, the individual
+submitting the contribution represents that they have authority to bind
+the organization to this Agreement.
+
+---
+
+## Contact
+
+For questions about this CLA, contact [licensing@nat-testing.io](mailto:licensing@nat-testing.io).
+
+---
+
+See also: [README.md — License](README.md#license) · [CONTRIBUTING.md — License and CLA](docs/contributing.md#license-and-cla)

nat_engine-1.0.5/COMMERCIAL_LICENSE.md

@@ -0,0 +1,76 @@
+# Commercial License — NeuroAgentTest (NAT)
+
+## Dual-License Model
+
+NeuroAgentTest (NAT) is dual-licensed:
+
+| Use Case | License |
+|---|---|
+| Open-source projects, academic research, personal use | [AGPL-3.0-or-later](LICENSE) |
+| Proprietary products, SaaS deployments, enterprise use | Commercial License (this document) |
+
+---
+
+## When Do You Need a Commercial License?
+
+You need a commercial license if **any** of the following apply:
+
+- You want to incorporate NAT into a **proprietary product** or service without open-sourcing your modifications.
+- You are deploying NAT as part of a **SaaS or hosted offering** and do not wish to comply with the AGPL-3.0 network-service copyleft requirement (which requires you to make your modified source available to users of your service).
+- You want to distribute NAT as part of a **closed-source application**.
+- You require **enterprise support, SLAs, or priority patches** not available under the open-source license.
+- You want **custom neural network tuning** or professional services from the NAT team.
+
+---
+
+## What the Commercial License Grants
+
+A NAT Commercial License provides:
+
+1. **Proprietary Use** — You may incorporate NAT into closed-source, proprietary products without the copyleft obligations of the AGPL-3.0.
+2. **No Copyleft Obligation** — You are not required to open-source modifications to NAT, even when deployed as a network service.
+3. **Priority Support & SLAs** — Access to dedicated support channels with defined response-time SLAs.
+4. **Custom Neural Network Tuning** — Professional services for tuning NAT's neural network parameters to your specific system under test.
+5. **Indemnification** — Additional IP indemnification clauses available at the enterprise tier.
+
+---
+
+## Licensing Tiers
+
+| Tier | Scope | Pricing |
+|---|---|---|
+| **Per-Seat** | Individual developer license | Contact us |
+| **Team** | Up to 25 developers | Contact us |
+| **Enterprise-Wide** | Unlimited developers within a single legal entity | Contact us |
+| **OEM / Reseller** | Embedding NAT in a product sold to third parties | Contact us |
+
+---
+
+## How to Obtain a Commercial License
+
+To inquire about a commercial license, please contact:
+
+**Email:** [licensing@nat-testing.io](mailto:licensing@nat-testing.io)
+
+Please include:
+- Your organization name
+- A brief description of your intended use case
+- Approximate team size or deployment scope
+
+We will respond within 2 business days.
+
+---
+
+## Contributor License Agreement
+
+All contributors to NAT must sign the [Contributor License Agreement (CLA)](CLA.md) before their contributions can be accepted. The CLA grants NAT maintainers the rights necessary to offer NAT under both the AGPL-3.0 and this Commercial License.
+
+---
+
+## Questions
+
+For any licensing questions not answered here, contact [licensing@nat-testing.io](mailto:licensing@nat-testing.io).
+
+---
+
+See also: [README.md — License](README.md#license) · [LICENSE](LICENSE) · [CLA.md](CLA.md)

nat_engine-1.0.5/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to NAT
+
+Thank you for your interest in contributing to **NeuroAgentTest (NAT)**!
+
+> **⚠️ CLA Required** — Before your first pull request is merged, you must agree
+> to the [Contributor License Agreement](.github/CLA.md). The CLA bot will
+> prompt you automatically when you open your first PR. See
+> [Signing the CLA](#signing-the-cla) below.
+
+For full contribution guidelines — development environment setup, code style,
+testing, and pull request process — see
+**[docs/contributing.md](docs/contributing.md)**.
+
+---
+
+## Quick Start
+
+```bash
+# Clone and install in editable mode with dev extras
+git clone https://github.com/bg-playground/MultiAgent-Neural-Network-Framework.git
+cd MultiAgent-Neural-Network-Framework
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run the test suite
+pytest tests/ -q
+```
+
+---
+
+## Signing the CLA
+
+NAT uses the [CLA Assistant](.github/workflows/cla.yml) GitHub Action to
+manage CLA signatures. When you open your first pull request:
+
+1. The bot will post a comment explaining the CLA.
+2. Read the full [Contributor License Agreement](.github/CLA.md).
+3. Reply to the bot's comment with:
+   > I have read the CLA Document and I hereby sign the CLA.
+4. Your GitHub username is added to [CLA_SIGNATORIES.md](CLA_SIGNATORIES.md)
+   and the check turns green for all future PRs.
+
+**Why a CLA?**
+
+NAT is dual-licensed (AGPL-3.0 for open source, Commercial License for
+enterprise). The CLA grants the project maintainers the rights needed to offer
+both licenses while protecting your rights as a contributor. See
+[docs/legal/licensing.md](docs/legal/licensing.md) for details.
+
+---
+
+## Licensing
+
+- NAT is licensed under **[AGPL-3.0-or-later](LICENSE)** for open-source use.
+- A **[Commercial License](COMMERCIAL_LICENSE.md)** is available for proprietary
+  and SaaS deployments where AGPL copyleft obligations are not acceptable.
+- All contributions are made under the CLA terms described above.
+
+For commercial licensing inquiries, contact
+[licensing@nat-testing.io](mailto:licensing@nat-testing.io).

nat_engine-1.0.5/Dockerfile

@@ -0,0 +1,77 @@
+# NeuroAgentTest (NAT) — Multi-Agent Neural Network Framework
+# Copyright (C) 2026 NAT Contributors
+# AGPL-3.0-or-later — see LICENSE for details
+# For commercial licensing: licensing@nat-testing.io
+
+# ---------------------------------------------------------------------------
+# Stage 1: Build — install dependencies and build the wheel
+# ---------------------------------------------------------------------------
+FROM python:3.11-slim-bookworm AS builder
+
+WORKDIR /build
+
+# Install build tooling
+RUN pip install --no-cache-dir build==1.2.2
+
+# Copy only the files needed to build the package
+COPY pyproject.toml README.md LICENSE ./
+COPY src/ ./src/
+
+# Build the wheel
+RUN python -m build --wheel --no-isolation
+
+# ---------------------------------------------------------------------------
+# Stage 2: Runtime — minimal production image
+# ---------------------------------------------------------------------------
+FROM python:3.11-slim-bookworm
+
+ARG BUILD_DATE
+ARG VCS_REF
+ARG VERSION=1.0.0
+
+LABEL org.opencontainers.image.title="NeuroAgentTest (NAT) API Server" \
+      org.opencontainers.image.description="REST API server for the NAT adaptive testing engine" \
+      org.opencontainers.image.licenses="AGPL-3.0-or-later" \
+      org.opencontainers.image.source="https://github.com/bg-playground/MultiAgent-Neural-Network-Framework" \
+      org.opencontainers.image.url="https://github.com/bg-playground/MultiAgent-Neural-Network-Framework" \
+      org.opencontainers.image.version="${VERSION}" \
+      org.opencontainers.image.revision="${VCS_REF}" \
+      org.opencontainers.image.created="${BUILD_DATE}" \
+      org.opencontainers.image.vendor="NAT Contributors"
+
+# Create a non-root user for security
+RUN addgroup --system nat && adduser --system --ingroup nat nat
+
+WORKDIR /app
+
+# Copy built wheel from builder stage and install it
+COPY --from=builder /build/dist/*.whl /tmp/
+
+RUN pip install --no-cache-dir /tmp/*.whl && rm /tmp/*.whl
+
+# Create data directories owned by the nat user
+RUN mkdir -p /app/data/scans /app/data/weights /app/data/regression && \
+    chown -R nat:nat /app/data
+
+# Switch to non-root user
+USER nat
+
+# Expose the default port
+EXPOSE 8080
+
+# Environment variables with sensible defaults
+ENV NAT_HOST=0.0.0.0 \
+    NAT_PORT=8080 \
+    NAT_LOG_LEVEL=info \
+    NAT_WORKERS=1
+
+# Built-in health check (uses the default port 8080; override via NAT_PORT env var)
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD python -c "import os,urllib.request; urllib.request.urlopen('http://localhost:'+os.environ.get('NAT_PORT','8080')+'/api/v1/health')" || exit 1
+
+# Default command: run the FastAPI server with uvicorn
+CMD uvicorn mannf.product.server:app \
+      --host "${NAT_HOST}" \
+      --port "${NAT_PORT}" \
+      --log-level "${NAT_LOG_LEVEL}" \
+      --workers "${NAT_WORKERS}"