📋 Document Metadata
Type: Security Policy | Audience: All Users | Complexity: Intermediate
Last Updated: 2026-09-07 | Status: Maintained
Cross-References: Comprehensive Security Guide | Deployment Security | MCP Security

The GNN (GeneralizedNotationNotation) project maintains a comprehensive multi-layered security approach covering development, deployment, and production environments.

📖 Complete Security Documentation: For comprehensive security information, see Security Guide

Candidate security evidence (2026-10-06): CodeQL is successful at 951dc7d3f58cfd3ef7106caa321c1d3c7d2ad51a; final-head renewal remains required. Alert #12 has a narrow request-string false-positive disposition. The trusted filesystem policy below retains its non-atomic concurrent-mutation limitation; GUI complexity alerts #13–#16 remain separate. See the closeout snapshot for scope and pending publication.

We are committed to ensuring the security of the GeneralizedNotationNotation (GNN) project.

🔄 Version Updates: This table is updated with each release. See CHANGELOG.md for version history.

ℹ️ Known Accepted Risks: The following vulnerabilities are documented and accepted:

• CVE-2024-39236 (gradio): Disputed — self-attack scenario only.
• CVE-2026-24049 (setuptools / bundled wheel): Path traversal in wheel.unpack(). setuptools 81.0.0 vendors wheel code that may be affected. Mitigation: GNN never calls wheel unpack or processes untrusted .whl archives at runtime; this is a build-tool-only surface. Monitor for a setuptools release that bundles wheel >= 0.46.2.
• CVE-2022-42969 / PYSEC-2022-42969 (py 1.11.0): Resolved — py package is no longer present in the dependency graph (removed from uv.lock as of 2026-05-07).

• Dependabot: Version updates are configured in .github/dependabot.yml (Python/uv.lock and GitHub Actions). Review alerts under GitHub → Security → Dependabot.

• PRs: .github/workflows/dependency-review.yml runs on pull requests to main.

• Local check (core runtime graph, no project package, no hashes):

  uv export --frozen --no-dev --no-hashes --no-emit-project -o /tmp/requirements-audit.txt
  uv tool run pip-audit -r /tmp/requirements-audit.txt

• Scheduled visibility: .github/workflows/supply-chain-audit.yml runs pip-audit weekly (non-blocking).

The GNN team and community take all security vulnerabilities seriously. We appreciate your efforts to responsibly disclose your findings, and will make every effort to acknowledge your contributions.

Primary Contact:

• Email: Send an email to blanket@activeinference.institute
• Subject Line: Use "Security Vulnerability in GNN Project"

GitHub Security:

• Platform: GitHub Security Advisories
• Repository: GeneralizedNotationNotation
• Benefits: Automated coordination with dependency maintainers

⚠️ Important: Please do not report security vulnerabilities through public GitHub issues.

When reporting a vulnerability, please provide:

• Clear description of the vulnerability and its impact
• Component identification: Affected files, modules, or pipeline steps
• Reproduction steps: Detailed steps to reproduce the issue
• Version information: Affected GNN versions and dependencies
• Environment details: Operating system, Python version, framework versions
• Proof of concept: If applicable, demonstration code (safely)
• Suggested mitigations: If you have ideas for fixes

LLM Integration Security (Pipeline Step 13):

• API key exposure in configuration files
• Prompt injection attacks through GNN files
• Unsafe code generation from LLM outputs

MCP Security (Pipeline Step 21):

• Model Context Protocol authentication issues
• Unsafe resource access patterns
• Data leakage through model context

Pipeline Security (All 25 Steps):

• Code injection through GNN file parsing
• Unsafe file operations in output generation
• Privilege escalation in execution steps

Once a security vulnerability is reported, we commit to:

Immediate Response (24-48 hours):

• Acknowledge receipt of the vulnerability report
• Assign a security team member as primary contact
• Begin initial assessment and triage

Investigation Phase (1-7 days):

• Validate and reproduce the vulnerability
• Assess severity using CVSS scoring
• Determine affected versions and components
• Develop initial mitigation strategies

Resolution Phase (Variable, based on severity):

• Critical: 24-72 hours for emergency patch
• High: 1-2 weeks for comprehensive fix
• Medium: 2-4 weeks for scheduled release
• Low: Next planned release cycle

Disclosure Phase:

• Coordinate responsible disclosure timeline
• Prepare security advisory and documentation
• Release patched versions across supported branches
• Publicly acknowledge contributor (unless requested otherwise)

Development Security:

• All code changes reviewed for security implications
• Automated security scanning in CI/CD pipeline
• Dependency vulnerability monitoring
• Regular security audits of critical components

Documentation Security:

• Security considerations in all operational guides
• Threat model documentation for each pipeline step
• Security configuration examples and best practices
• Incident response procedures and playbooks

Environment Setup:

• Use isolated Python virtual environments
• Keep dependencies updated: uv sync --refresh
• Validate GNN file sources before processing
• Use secure API key storage (environment variables, not files)

Code Security:

• Review generated code before execution
• Validate all inputs to GNN parsers
• Use sandbox environments for testing unknown models
• Follow secure coding practices for extensions

Infrastructure Security:

• Deploy with minimal required privileges
• Use encrypted connections for all API calls
• Implement proper logging and monitoring
• Regular security updates and patches

Configuration Security:

• Secure API key management (Azure Key Vault, AWS Secrets Manager)
• Network segmentation for GNN processing
• Input validation for all user-provided GNN files
• Output sanitization for generated code

Built-in security controls (env-var opt-in, 2026-08-14):

• GNN_API_KEY — require a matching X-API-Key header on the FastAPI API; non-loopback binds are refused unless set or GNN_ALLOW_INSECURE_BIND=1.
• GNN_SANDBOX — off / prefer / require wrapping of rendered-script execution under firejail / bubblewrap / nsjail (degrades loudly, never silently).
• GNN_ALLOW_UNSAFE_EXEC=1 — explicit escape hatch to bypass the pre-execution AST gate (trusted-local research only).
• GNN_MCP_TOKEN / GNN_MCP_RATE_LIMIT_PER_MINUTE — bearer auth and per-client rate limiting for the MCP HTTP server.

The local API resolves request paths inside a trusted, locally managed checkout. Its shared path validator checks lexical containment, rejects existing symlink components, and checks resolved containment before directory creation or returning paths to the request handlers. Rejected paths produce a validation error before backend processing. These checks constrain request strings; they do not provide descriptor-based, atomic confinement against a separate actor replacing filesystem entries between validation and use. Authentication and non-loopback binding controls remain separate from this filesystem limitation. Use a checkout whose filesystem writers are trusted; hostile concurrent filesystem mutation is outside the current API contract.

PyMDP Security:

• Validate matrix dimensions before processing
• Sanitize numerical inputs for stability
• Monitor memory usage for large state spaces

RxInfer.jl Security:

• Validate Julia code generation outputs
• Secure inter-process communication with Julia
• Monitor computational resource usage

ActiveInference.jl Security:

• Validate Julia ActiveInference.jl code generation outputs
• Secure inter-process communication with Julia
• Monitor computational resource usage for ActiveInference.jl simulations

LLM Integration Security:

• Never include sensitive data in prompts
• Validate all LLM-generated outputs
• Use prompt injection prevention techniques
• Implement rate limiting for API calls

• Complete Security Framework - Comprehensive security guide
• Deployment Security - Production security configurations
• MCP Security - Model Context Protocol security measures

• PyMDP Security - PyMDP-specific security
• RxInfer.jl Security - Julia integration security
• ActiveInference.jl Security - ActiveInference.jl integration security
• LLM Security - AI integration security practices

• Security Incident Response - Response procedures
• Vulnerability Assessment - Assessment frameworks
• Security Monitoring - Monitoring and alerting

• Security Review: Participate in security-focused code reviews
• Vulnerability Research: Help identify potential security issues
• Documentation: Improve security documentation and guides
• Tool Development: Create security-focused tools and utilities

• Security Announcements: Subscribe to repository notifications
• Release Notes: Check CHANGELOG.md for security fixes
• Community Forum: Engage in security discussions
• Best Practices: Share security configurations and patterns

We appreciate your help in keeping GeneralizedNotationNotation secure across all dimensions: physical, digital, and cognitive.

🔗 Related Documentation: Security Guide | Deployment Security | Contributing Security