AI-SPM v1.0.0 — AI Security Posture Management

[dshapi]

AI-SPM v1.0.0 — AI Security Posture Management

Release date: 2026-04-25
Codename: "MCP"

First production release of the AI Security Posture Management. Customers
can now upload their own AI agents as a single Python file, deploy
them into sandboxed containers, and have them chat through the full
security pipeline — prompt-guard → policy decider → Kafka → output-guard
— with attached policies, conversation memory, web search, and a live
activity timeline visible in the admin UI.

---

Highlights

• End-to-end agent chat through the existing AI-SPM security pipeline,
  with attached per-agent policies enforced on every turn.
• Drop-in agent uploads. Operator drops in a single agent.py, the
  platform validates it, mints per-agent tokens, spawns a sandboxed
  Docker container, and routes traffic through Kafka. No custom image
  required for the five example agent shapes we ship.
• Provider-agnostic LLM proxy. Native dispatch for Anthropic and
  Ollama (both OpenAI-compatible and native modes); operators switch
  providers in the UI without restarts or code changes.
• Live observability. Every chat turn, web-search call, and LLM
  call emits a lineage event that lands in session_events and tails
  in the per-agent Activity tab in the admin UI within 5 seconds.
• DB-backed configuration. The agent SDK fetches its connection
  bundle from the controller at boot — no platform secrets in the
  agent's container env.

---

What's new

Agent runtime control plane

• POST /api/spm/agents — upload agent.py (multipart) with
  deploy_after=true. Validates syntax, top-level async def main,
  and dry-import; mints per-agent mcp_token + llm_api_key; creates
  the per-agent Kafka topics; spawns the runtime container; polls for
  the SDK's aispm.ready() handshake.
• POST /api/spm/agents/{id}/start | /stop — idempotent kick;
  UI surfaces a persistent "working…" spinner until the polled
  runtime_state actually changes.
• DELETE /api/spm/agents/{id} — stops the container, drops the
  topics, deletes the row.
• POST /api/spm/agents/{id}/chat — full pipeline, SSE response.
• GET /api/spm/agents/{id}/bootstrap — DB-backed SDK boot. The
  agent's container only needs three env vars (AGENT_ID,
  MCP_TOKEN, CONTROLLER_URL); everything else is fetched here.
• GET /api/spm/agents/{id}/policies + PUT — atomic-replace
  attach/detach. The chat handler reads linked_policies per turn
  and forwards them to OPA so policies can scope evaluation.
• GET /api/spm/agents/{id}/activity — unified timeline (chat
  turns + AgentToolCall + AgentLLMCall), newest-first, capped at
  200 rows. Polled by the Activity tab.

Agent-side SDK (agent_runtime/aispm)

• aispm.ready() — lifecycle handshake.
• aispm.chat.subscribe() / reply() — Kafka I/O. Consumer uses
  auto_offset_reset="earliest" so the very first message after deploy
  is never silently dropped during consumer-group join.
• aispm.chat.history(session_id, limit) — replay persisted turns;
  example agents use this for conversation memory across turns.
• aispm.mcp.call("web_fetch", ...) — JSON-RPC over HTTP to the MCP
  server; web_fetch is Tavily-backed.
• aispm.llm.complete(messages=, model=…) — OpenAI-compatible call
  through spm-llm-proxy; the SDK no longer pins a default model so
  the operator's chosen provider model wins.
• aispm.get_secret(name) — per-agent secret store.
• aispm.log("step", trace=…) — structured lineage line on stdout.

Provider dispatch (spm-llm-proxy)

connector_type	Endpoint	Auth header	Model source
anthropic	{base_url}/v1/messages	x-api-key + anthropic-version: 2023-06-01	integration model (payload model honoured only when it starts with claude)
ollama (/v1)	{base_url}/chat/completions (OpenAI-compatible)	none	payload model > integration model > llama3.1:8b fallback
ollama (other)	{base_url}/api/chat (native)	none	payload model > integration model > llama3.1:8b fallback

Switching provider is a UI dropdown change on the AI-SPM Agent Runtime
Control Plane (MCP) integration row — no restart, no agent re-deploy.

Observability (AgentToolCallEvent, AgentLLMCallEvent)

• spm-mcp emits AgentToolCallEvent after every web_fetch,
  capturing tool name, args, ok/error, and duration_ms.
• spm-llm-proxy emits AgentLLMCallEvent after every chat-completion
  call (Anthropic and Ollama paths), capturing model, prompt and
  completion token counts, and ok/error.
• Both events publish to cpm.global.lineage_events. The existing
  lineage_consumer persists them into session_events automatically.
• Best-effort by design: a producer init failure never blocks the
  serving path. A lineage_producer.send failed warning is the only
  signal when Kafka is unreachable; chat keeps working.

Admin UI

• Inventory → Agents tab lists live agents alongside mock rows
  with a runtime-state pip and risk tint.
• PreviewPanel (right-side panel on row click) carries the
  Run/Stop toggle, Open Chat, View Detail, and Delete asset
  actions.
• AgentChatPanel (300px inline panel) opens from PreviewPanel's
  Open Chat. Composer pinned to bottom (min-h-0 + max-h(100vh-120px)
  so it can never be pushed off-screen by long chat history).
• AgentDetailDrawer (560px overlay) opens from PreviewPanel's
  View Detail button. Five tabs: Overview, Configure, Activity
  (live tail, polls every 5s), Sessions, Lineage.
• PolicySelector lets operators attach/detach policies on a live
  agent without leaving the panel.
• Add Integration modal: enum_integration fields render as real
  dropdowns of existing integrations (no more pasting UUIDs).
• Run/Stop button stays in a "working…" state until the next poll
  observes the actual runtime-state change.

Examples

A new top-level Example agents/ folder ships five
ready-to-deploy agents — one per agent_type enum value:

File	agent_type	Demonstrates
custom_agent.py	custom	Bare-SDK happy path with aispm.chat.history() conversation memory and a strong web-search prompt.
langchain_agent.py	langchain	Off-the-shelf LangChain AgentExecutor + @tool calling our MCP / LLM proxies.
llamaindex_agent.py	llamaindex	LlamaIndex chat-engine routed through aispm.llm, with a hand-rolled retrieval fallback.
autogpt_agent.py	autogpt	Self-prompting plan → execute → reflect loop, capped at 3 hops.
openai_assistant_agent.py	openai_assistant	OpenAI Assistants-style request shape (system + user + tools), no framework.

The runtime image now has langchain==0.3.*, langchain-openai==0.2.*,
llama-index-core==0.11.*, and llama-index-llms-openai-like==0.2.*
baked in, so langchain_agent.py and llamaindex_agent.py deploy
cleanly without bringing your own image.

---

Bug fixes

• paused agent immediately after deploy. The upload route's
  _wait_for_ready was reading a stale identity-mapped Agent row
  from its own SQLAlchemy session and timing out, then overwriting
  the (correctly running) row to crashed. Fixed with db.expire_all()
  on every poll iteration.
• First message after deploy silently dropped. The agent's Kafka
  consumer joined the group with the default auto_offset_reset= "latest", so any message produced between aispm.ready() flipping
  the row to running and the consumer registering with the broker
  was skipped. Fixed by switching to earliest.
• Prompt blocked by safety guard. (S2) on the literal word "yes".
  Three different code sites (two adapters and one module-level
  function injected via guard_fn=) had the same anti-pattern that
  forced verdict=block whenever any S1–S15 category appeared, even
  when the guard's own verdict was allow. Replaced with a length-based
  bypass for inputs under GUARD_MIN_TEXT_LEN=8 chars and a
  score-threshold (GUARD_BLOCK_SCORE=0.6) gate on the
  category-escalation path.
• 502 Load failed on chat. The agent_chat.py SSE handler was
  importing aiokafka lazily but the package wasn't in spm-api's
  requirements. Added the dep.
• 500 ModuleNotFoundError: No module named 'services.spm_api' in
  both spm-llm-proxy and spm-mcp. Both fell back to a brittle
  cross-service import. Inlined _decode_secret and dropped the
  cross-service registry lookup so each service is self-contained.
• POST /v1/chat/completions returning 500. The proxy was hardcoded
  to Ollama's /api/chat shape; pointing Default LLM at Anthropic
  produced a 404 from api.anthropic.com. Now branches on
  connector_type and translates request + response shape per provider.
• web_fetch 404 on http://spm-mcp:8500/mcp. The MCP server
  registered tools with FastMCP but never mounted FastMCP's HTTP
  transport. Added an explicit POST /mcp JSON-RPC handler.
• spm-mcp crashing at startup with TypeError: issubclass() arg 1 must be a class. from __future__ import annotations in
  tools/web_fetch.py made FastMCP's annotation introspection blow up.
  Removed.
• agents.code_blob self-heal. Operators who rm'd the bind-mount
  source previously broke the agent permanently. The runtime image
  now rewrites the file from agents.code_blob (DB-stored agent.py
  source) on every spawn.
• Integrations page blank after creating the agent-runtime row.
  OwnerAvatar crashed with Cannot read properties of null (reading 'split') when the new row had no owner. Defensive null-name guard.
• null is not an object (evaluating 'n.id') UI crash. The
  mergeAgents / mergedAllAssets / adaptLiveAgent chain had no
  null filtering, so a poll race during a failing fetch could leave a
  null entry in the array. All three layers now filter falsy entries.
• Pasting UUIDs into agent-runtime config fields. SchemaForm
  didn't handle type: "enum_integration" and fell back to a text
  input. Now renders a dropdown of existing integrations filtered by
  the connector's declared options_provider.
• AgentChatPanel composer pushed below the fold. Missing
  min-h-0 on the flex column meant the message list grew unbounded.

---

Operator changes

• New integration to configure on first install: AI-SPM Agent
  Runtime Control Plane (MCP), under Integrations → AI Providers.
  Set its Default LLM field to your existing AI Provider integration
  (e.g. Anthropic, Ollama) and Tavily Integration to your Tavily
  row. The proxy and MCP server resolve through this row at every call,
  so changing the upstream provider is a UI dropdown change with no
  restart.
• Runtime image rebuild required to pick up the new framework
  batteries:

  docker compose -f docker-compose.yml -f docker-compose.auth.yml \
      --profile build-only build --no-cache agent-runtime-build

  Adds ~200 MB to the image (LangChain + LlamaIndex). Existing agent
  containers should be force-removed before the next deploy:

  docker ps -a --filter 'name=agent-' -q | xargs -r docker rm -f

• New env-var knobs (all have safe defaults):

  Variable	Service	Default	Purpose
  GUARD_BLOCK_SCORE	api, spm-api	0.6	Min guard score to escalate allow + category to block.
  GUARD_MIN_TEXT_LEN	api, spm-api	8	Inputs shorter than this skip the guard entirely.
  AGENT_READY_TIMEOUT_S	spm-api	30	Deploy poll budget for the SDK's ready() handshake.
  AGENT_CHAT_REPLY_TIMEOUT_S	spm-api	120	How long the chat round-trip waits for an agent reply on chat.out.
  AGENT_CONTROLLER_URL	spm-api	http://spm-api:8092	What gets injected as CONTROLLER_URL into spawned agent containers.
  KAFKA_BOOTSTRAP_SERVERS	spm-mcp, spm-llm-proxy	kafka-broker:9092	Lineage producer bootstrap.

---

Database migrations

Three new alembic revisions auto-apply on spm-api startup:

• 005_agent_runtime_control_plane — agents, agent_chat_sessions,
  agent_chat_messages tables; agent_type enum.
• 006_agent_policies — join table agent_policies(agent_id, policy_id, attached_at, attached_by) with cascade-on-agent-delete.
• 007_agent_code_blob — adds agents.code_blob TEXT so the runtime
  can self-heal a deleted host file.

All migrations are forward-only; no data loss on upgrade. 005 is
idempotent against duplicate-enum-create errors so re-applying is safe.

---

Tests

• 514 unit + integration tests green (Python).
• 3 e2e smoke tests in tests/e2e/ (skip cleanly without
  docker-compose; run when the stack is up).
• New TestChatWithPolicySmoke covers the full Phase 4 path: register
  agent → wait for running → attach policy → POST /chat SSE →
  assert reply text + activity timeline contains both user and agent
  turns → detach policy → delete.

---

Documentation

• New top-level README.md sections: Deploying an agent,
  Adding a new integration (LLM, Tavily, etc.), Adding an LLM
  specifically — minimum setup, Adding a new asset type.
• docs/agents/operator-quickstart.md extended with the Phase 4
  end-to-end flow diagram, bring-up checklist, provider dispatch
  table, gotchas table, and env-knob reference.
• Example agents/README.md covers the
  five example agents, what each demonstrates, what's baked into the
  runtime image, and how to read the Activity tab for debugging.
• Plan documents committed for each phase under
  docs/superpowers/plans/2026-04-25-agent-runtime-control-plane-phase-{1..4}-*.md.
• Design spec at
  docs/superpowers/specs/2026-04-25-agent-runtime-control-plane-mcp-design.md.

---

Upgrade notes

For an existing AI-SPM stack, this is a backwards-compatible feature
release — no breaking changes to existing connectors, policies, or
chat behaviour. To get the new agent runtime online:

git pull
docker compose build --no-cache spm-api spm-mcp spm-llm-proxy ui

# Runtime image (LangChain + LlamaIndex baked)
docker compose -f docker-compose.yml -f docker-compose.auth.yml \
    --profile build-only build --no-cache agent-runtime-build

# Recreate
docker compose up -d --force-recreate spm-api spm-mcp spm-llm-proxy ui

# Stop any stale agent containers (they have the old env contract)
docker ps -a --filter 'name=agent-' -q | xargs -r docker rm -f

Then in the UI:

1. Configure an LLM provider integration (Anthropic / Ollama / etc.).
2. Configure the AI-SPM Agent Runtime Control Plane (MCP)
   integration; pick the LLM provider and Tavily on it.
3. Inventory → Agents → Register Asset → drop in
   Example agents/custom_agent.py
   → type custom → Register & Deploy.
4. Open Chat. Send a message.

---

Known limitations

• Per-agent requirements.txt isn't supported yet; agents that
  need packages outside the baked-in set (LangChain, LlamaIndex, the
  SDK transport deps) require forking the runtime Dockerfile. Planned
  for V2.
• AgentDeployedEvent / AgentStartedEvent / AgentStoppedEvent
  dataclasses exist in platform_shared/lineage_events.py but aren't
  yet emitted from agent_controller. Only AgentChatMessageEvent,
  AgentToolCallEvent, and AgentLLMCallEvent flow through
  lineage_consumer today.
• Streaming token responses (aispm.chat.stream) is a stub that
  raises NotImplementedError on write(). The SSE shape supports
  per-token frames, but the agent → Kafka path is one-message-per-reply.
  Planned for V1.5.
• Multi-tenant enforcement on agent rows is on a single boundary
  (the list endpoint scopes by tenant_id); other surfaces are
  effectively single-tenant. V2 enforces strict isolation everywhere.
• Plaintext mcp_token / llm_api_key at rest. The columns are
  admin-only and never returned in API responses, but V2 will encrypt
  with the existing Fernet key.
• OPA policy DSL for agent-runtime context is a thin wrapper over
  the existing spm/prompt/allow and spm/output/allow rules; rules
  that reference input.linked_policies need to be authored.

---

What's next (V1.1 / V2 roadmap candidates)

• Per-agent requirements.txt builds.
• AgentLifecycle* event emission from agent_controller.
• Per-token SSE streaming through the chat pipeline.
• Multi-tenant enforcement on every agent surface.
• Encrypted-at-rest agent tokens.
• Streaming Activity tab (SSE instead of 5s polling).
• More built-in MCP tools beyond web_fetch.

---

Acknowledgements

This release was built end-to-end across Phase 1 (backend), Phase 2
(SDK), Phase 3 (UI), Phase 4 (chat pipeline), and Phase 4.5
(observability) over a single working day, against a live AI-SPM stack
with iterative feedback at each step.

Thanks to the operators who hammered the chat with yes until the
guard-model false positive surfaced.

---

This discussion was created from the release AI-SPM v1.0.0 — AI Security Posture Management.

[musaabhasan]

For an AI-SPM platform, the most valuable next control would be posture drift detection across the full agent deployment lifecycle.

Useful drift dimensions:

• uploaded agent file hash changed,
• policy version changed,
• tool set changed,
• sandbox image or runtime changed,
• provider/model route changed,
• memory configuration changed,
• network egress changed,
• token scope changed,
• guardrail decision rate changed materially.

Each drift event should be classified as expected change, review-required change, or release-blocking change. The evidence record should include previous value, new value, approver, policy version, and whether regression tests were rerun.

That gives the platform a posture-management story beyond runtime blocking: it can show whether the deployed agent is still the agent that was originally reviewed.

[dshapi]

Thanks for the input , let's open an issue (issues) for that.
I'm in the middle Of security review by Claude fixing some issues - I will be happy to add additional ones to the list

[musaabhasan]

Opened this as issue #27: #27

I kept the scope focused on posture drift rather than a broad feature request: baseline-vs-current comparison for agent definitions, MCP tool manifests, identity scopes, runtime boundaries, memory/RAG sources, guardrail decision rates, and provider routes. That should make it easier to review alongside the current security hardening work.