LegionForge — Security-Native AI Agent Framework

2247 Tests Passing

7 Guardian Checks

11 Threat Classes

29 Injection Patterns

0 LLM calls in security hot path

💬 Submit Tasks From Anywhere

LegionForge meets you where you already are. Every interface connects to the same secure execution pipeline.

Web UI

localhost:8080/ui — live token streaming, tool call blocks, session history, dark/light mode

Discord

!<task> in any channel — bot replies and edits the message live as the agent streams

/<task> to your bot — polling-based, no public URL needed

Slack

!<task> via Socket Mode — no public URL, just a bot token and an app token

Webhook

POST :8081/inbound — HMAC-SHA256 verified, works with n8n, Zapier, or any HTTP client

REST API

POST /tasks + GET /tasks/{id}/stream — full SSE streaming with A2A + MCP endpoints

⛓ Crystallization Pipeline

When agents solve the same deterministic problem repeatedly, LegionForge crystallizes the solution into a signed, containerized tool — zero LLM overhead for routine work.

Observer ──▶ Crystallizer ──▶ Pre-HITL Analyzer ──▶ Human Gate ⏸ ──▶ Ed25519-Signed Tool ✓

The Pre-HITL Analyzer runs AST guards (subscript bypass, MRO traversal, globals()/locals() hijack) and behavioral diffs before any human reviews a proposal. No tool reaches production without human approval.

🛡 Guardian Security Sidecar

A standalone FastAPI process (:9766) with a deterministic-only 7-check pipeline on every tool call. No LLM calls. Unpoisonable. Fails safe to halt on any error.

🚫

Check 0 — Revocation

REVOKED tools are blocked before any other check. Cache TTL: 10 seconds — revocation takes effect in under 10s without any restart.

🔐

Check 1 — Registry + Hash

Tool must be APPROVED in the registry. SHA-256 hash must match the registration record exactly.

🧱

Check 2 — Capability Boundary

Negative capability list blocks unauthorized tool categories per agent profile. Agent cannot call what it wasn't granted.

🔍

Check 3 — Destructive Patterns

Regex detection of destructive command patterns in tool arguments — caught before execution, not after.

📋

Check 4 — Sequence Contract

Agent tool sequences are registered at startup. Deviations trigger the sandbox retry tier — never a silent pass.

✍️

Check 5 — Ed25519 Signature

Crystallized tools must carry a valid Ed25519 signature from the operator-held signing keypair.

⚡

Check 6 — Adaptive Rules

Human-approved threat rules from the Threat Analyst agent hot-reload every 10 seconds. No Guardian restart needed.

⚠️ Threat Coverage

Tool Poisoning

SHA-256 hash validation at registration + Ed25519 cryptographic signing

Rug-Pull

Hash mismatch detection + signed tool versioning — tool can't change after approval

Prompt Injection

29-pattern sanitizer (Tier 1 halt / Tier 2 log) + NFKC normalization + zero-width char stripping + RAG provenance scoring

Capability Amplification

Negative capability list enforced by Guardian Check 2 — agent cannot grant itself new capabilities

Resource Bomb / Economic DOS

Pre-execution token cost estimator + per-user daily budgets + per-provider rate limits with 80%/100% alerts

Credential Theft

macOS Keychain / ~/.pgpass credential storage + PII redaction on all outbound API calls and LangSmith traces

RAG / Memory Poisoning

Document provenance scoring at ingestion + embedding trust threshold flagging

Multi-Agent Cascade

Orchestrator-only routing + signed inter-agent messages — sub-agents cannot spawn peers

Supply Chain

AI-BOM + signed tool library + SHA-256 GGUF model integrity verification

TOCTOU

approved_snapshot stored pre-execution; post-execution result verified against snapshot in SecureToolNode

AST Bypass

Subscript, MRO traversal, globals()/locals() hijack detection in crystallization pre-HITL analyzer

🔑 Multi-Provider Authentication

Five auth backends — swap without touching agent code. Set gateway.auth_provider in your hardware profile YAML.

🔑

API Key (default)

bcrypt-hashed Bearer tokens stored in PostgreSQL. make create-user generates keys with optional daily budget.

🌐

OIDC

Google, Okta, Auth0, Azure AD, Keycloak, Cognito — any standards-compliant OIDC provider.

🐙

GitHub OAuth

GitHub OAuth app tokens. Identity stored as github:<user-id>.

🏢

LDAP

OpenLDAP, Active Directory. HTTP Basic auth. Supports bind DN + search base configuration.

🎫

Kerberos / GSSAPI

Full MIT Kerberos implementation. Negotiate auth. Requires OS-level KDC + keytab. See docs/SCALING.md.

🗺 Phase Roadmap

All phases complete.

Phase 0

PostgreSQL + pgvector, async LLM factory (Ollama/OpenAI/Anthropic), health server

✓ complete

Phase 1

Researcher agent, tool registry + SHA-256 hash validation, capability boundaries, threat logging

✓ complete

Phase 2

Docker, Guardian sidecar, immutable audit log (SHA-256 hash chain), RAG provenance

✓ complete

Phase 3

JWT task tokens + ACLs, sub-agent orchestrator, sandbox retry tier

✓ complete

Phase 4

Threat Analyst agent, adaptive Guardian rules, AI Bill of Materials

✓ complete

Phase 5

Crystallization Pipeline — Observer → Crystallizer → Pre-HITL Analyzer → Ed25519-signed tools

✓ complete

Phase 5.5

DB RBAC, AST bypass guards, tool revocation, TOCTOU mitigation, Ollama model integrity

✓ complete

Phase 6

PentestAgent — air-gapped red-team bot, 8 attack classes × 3 variants, stop-at-proof

✓ complete

Phase 7

Guardian feedback loop (pentest → threat rules → hot-reload), SECURITY.md, v1.0 hardening

✓ complete

Phase 8

Gateway (:8080), task queue, SSE streaming, web UI, A2A + MCP endpoints, Discord connector

✓ complete

Phase 9

langchain 1.x migration, 5-tool library, parallel agent fan-out, Phase 9.5 hardening sprint

✓ complete

Phase 10

Multi-user auth — DB stream tokens, per-user daily budgets, /usage/me, user management CLI

✓ complete

Phase 11

SecureToolNode fix, 38 integration tests, AuthBackend protocol, Dockerfile.gateway, SCALING.md

✓ complete

Phase 12

OIDCBackend, GitHubOAuthBackend, LDAPBackend, KerberosBackend — multi-scheme require_user

✓ complete

Phase 13

Real GSSAPI Kerberos backend, Redis-backed stream tokens, multi-instance docker-compose + Nginx

✓ complete

Phase 14

Redis global budget counters, Prometheus /metrics endpoint, X-Request-ID trace middleware

✓ complete

Phase 15

Polished web UI — localStorage key + history, cancel, tool call blocks, live timer, copy, keyboard shortcuts

✓ complete

Phase 16

Telegram (polling), Slack (Socket Mode), Webhook (HMAC-SHA256 + async callback) connectors

✓ complete

Phase 60–381

381-tool operator dashboard — every gateway API endpoint surfaced as a UI function with smoke tests

✓ complete

Security

Extended exfiltration detection, NFKC normalization, DESTRUCTIVE_PATTERN DB logging, PostgreSQL scram-sha-256

✓ complete

Web tools

web_fetch_js — Playwright headless browser for JS-rendered pages; two-layer SSRF guard; private-IP PII fix

✓ complete

Guardian G1–G4

legionforge_guardian standalone package; backward-compat shim; python -m legionforge_guardian; v0.2.0 on PyPI with /health, /metrics, canary, /invalidate-cache; public repo at LegionForge/LegionForge-Guardian with auto-sync Action

✓ complete

Memory — all 5 gaps

DB-backed SOUL.md persona (Gap 1), user prefs bootstrap (Gap 5), memory_write/memory_recall tools (Gap 3), daily episodic summaries (Gap 2), pre-compaction flush (Gap 4) — full OpenClaw parity

✓ complete

UI polish

4 color themes (Solarized, Warm, Nord, High-Contrast) + multi-theme cycler + favicon; session continuity sidebar with per-session turn count badge

✓ complete

Phase H

Session continuity sidebar — collapsible session list, per-session turn count badge, resume prior conversations with full context

✓ complete

Phase I

Multi-modal image input — paste or drag images into the task input; vision API routing to Ollama vision models or Anthropic Claude (auto-detected by model capability)

✓ complete

Security sprint

8 targeted hardening fixes — timing oracle, SSRF guard, log injection, prompt injection tightening, pgvector isolation, budget atomicity, concurrency, admin audit trail

✓ complete

⚡ Quick Start

Repository not yet public. The source will be available to clone after UAT completes. Watch this repo for the release announcement, or email jp@legionforge.org for early access.

# Coming soon — clone and bootstrap

git clone https://github.com/LegionForge/LegionForge.git

cd LegionForge

make check

make db-init

make test-smoke

# ✓ 2247 passed in ~21s

make start

# open http://localhost:8080/ui

📬 Status

⚠ v0.7.1-alpha — Active Development. This project is not yet at a stable 1.0 release. APIs and configuration formats may change before v1.0.0.

The security stack, gateway, and operator dashboard are functionally complete and tested. 2247/2247 tests passing. Phases 0–381 + G1–G4 complete, plus web browser tools, Guardian v0.2.0 on PyPI, full agent memory model (all 5 gaps — OpenClaw parity), multi-modal image input (Phase I), session continuity sidebar (Phase H), 4 UI themes, and targeted security hardening (8 fixes — timing oracle, SSRF, log injection, budget atomicity). Active development toward v1.0.0 public release.

The source will be available at github.com/LegionForge/LegionForge after UAT completes. Bugs, questions, and commercial licensing inquiries via GitHub Issues or jp@legionforge.org. Security vulnerabilities: coordinated 90-day disclosure window — email security@legionforge.org.