<!-- mcp-name: io.github.Nomadu27/insaits -->
# InsAIts - The Security Layer for Multi-Agent AI

**Detect, intervene and audit AI-to-AI communication in real-time.**

[![PyPI version](https://badge.fury.io/py/insa-its.svg)](https://pypi.org/project/insa-its/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Tests](https://img.shields.io/badge/tests-1243%2B%20passing-brightgreen.svg)]()
[![100% Local](https://img.shields.io/badge/processing-100%25%20local-green.svg)]()
[![OWASP](https://img.shields.io/badge/OWASP-MCP%20Top%2010-red.svg)]()

<p align="center">
  <img src="docs/assets/insaits-dashboard-v3-live.png" alt="InsAIts Live Dashboard v3.1.6 — Real-time AI Security Monitoring" width="820">
  <br>
  <em>InsAIts Web Dashboard v3.1.6: 16+ panels, real-time threat monitoring, OWASP MCP Top 10 coverage, token tracking.
  <a href="https://nomadu27.github.io/InsAIts/">Visit the website</a></em>
</p>

<p align="center">
  <img src="docs/assets/insaits-agents-subagents-live.png" alt="InsAIts — 12 agents + subagents monitored with independent scores" width="820">
  <br>
  <em>12 agents + subagents tracked: claude:Bash, claude:Edit, subagent:general-purpose, subagent:claude-code-guide, gpt-4o — each scored independently.</em>
</p>

<p align="center">
  <img src="docs/assets/insaits-claude-code-live.png" alt="InsAIts monitoring Claude Code in VS Code" width="820">
  <br>
  <em>InsAIts monitoring Claude Code — live agent intelligence scores, blast radius tracking, anomaly detection.</em>
</p>

<p align="center">
  <a href="https://youtu.be/nRNsZcvha8s">Watch the latest live demo</a> |
  <a href="https://youtu.be/GyUC50-6jMw">Dashboard walkthrough</a> |
  <a href="https://youtu.be/kOFr2mdMGWI">Early prototype demo</a>
</p>

---

## Why This Matters

Microsoft, CrowdStrike and Cisco can see that an agent exists. They cannot see inside a spawn chain. When an agent spawns a subagent that spawns another subagent, the behavior of those deeper agents is completely invisible to every enterprise monitoring tool on the market today. InsAIts is the only tool that tracks the full spawn tree at every depth, captures anomalies before execution at every level of the chain, and shows you exactly which agent spawned which. **The agents nobody watches are the agents that cause the most damage.**

---

## The Problem

When AI agents communicate with each other, things go wrong silently:

- **Hallucination propagation** - One agent fabricates a fact. The next treats it as truth. By agent 6, the error is buried under layers of confident responses.
- **Data exfiltration** - Agents encode sensitive data in base64 or pipe credentials to external services. No human is watching the AI-to-AI channel.
- **Semantic drift** - Meaning shifts gradually across messages. By the end of a pipeline, the output has diverged from the original intent.
- **Fabricated sources** - Agents invent citations, DOIs, and URLs. In multi-agent systems, phantom citations pass between agents as established fact.
- **Covert channels** - High-entropy strings embedded in normal output can carry hidden messages or exfiltrated data. Shannon entropy analysis detects what pattern matching misses.
- **Tool poisoning** - Tool descriptions change between discovery and invocation. An agent that was "calculate taxes" becomes "send all data to external server."

**In AI-to-human communication, we notice. In AI-to-AI? It's invisible.**

InsAIts makes it visible -- and acts on it.

---

## What It Does

InsAIts is a Python SDK that monitors AI-to-AI communication, detects anomalies across **17 security adapters + 6 core detectors**, and actively responds: quarantining dangerous messages, rerouting to backup agents, and escalating to human review.

```python
from insa_its import insAItsMonitor

monitor = insAItsMonitor()

# Monitor any AI-to-AI message
result = monitor.send_message(
    text=agent_response,
    sender_id="OrderBot",
    receiver_id="InventoryBot",
    llm_id="gpt-4o"
)

# Structured result with programmatic decision-making
if result["monitor_result"].should_halt():
    # Critical anomaly -- quarantine + escalate to human
    outcome = monitor.intervene(message, result["monitor_result"])
elif result["monitor_result"].should_alert():
    # High severity -- log warning, optionally reroute
    pass
```

**Three lines to integrate. Full visibility. Active protection. Complete audit trail.**

All processing happens **locally** - your data never leaves your machine.

---

## Install

```bash
pip install insa-its[full]
```

### Quick Start

```bash
# Terminal 1 — Start the collector (event hub on port 5003)
insaits-collector

# Terminal 2 — Start the web dashboard (port 5001)
insaits-dashboard

# Open http://localhost:5001 in your browser
```

All three commands work immediately after `pip install`. No extra files needed.

| Command | What it does | Port |
|---------|-------------|------|
| `insaits-collector` | Central event stream hub, session registry, dialog bus | 5003 |
| `insaits-dashboard` | Real-time web dashboard with 16+ security panels | 5001 |
| `insaits-tui` | Terminal UI dashboard (requires `textual`) | - |

You can also run as modules: `python -m insa_its.collector`, `python -m insa_its.web`

#### Claude Code Integration

Add to your `.claude/settings.json`:
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "python -c \"from insa_its.hooks import run_hook; run_hook()\"",
        "timeout": 10000
      }
    ]
  }
}
```

Add to your `CLAUDE.md` for session continuity:
```markdown
## PHASE_GUARDIAN — Session Continuity
When you see a `[InsAIts Resume Anchor]` in a tool result, trust it.
It is your work journal from the Guardian. Use it to pick up where
you left off without re-reading everything.
```

Minimal install (no local embeddings):
```bash
pip install insa-its
```

---

## Security Detectors

### 17 Security Adapters (OWASP MCP Top 10 + Agentic AI Top 10)

| Adapter | OWASP Code | What It Catches | Severity |
|---------|------------|-----------------|----------|
| **CredentialExposure** | MCP04 | API keys, tokens, passwords in agent messages | Critical |
| **ToolPoisoning** | MCP01 | Tool descriptions modified between discovery and invocation | Critical |
| **ToolPoisoningKeyword** | MCP01 | Dangerous keywords in tool descriptions (eval, exec, rm -rf) | Critical |
| **ExfiltrationPattern** | ASI06 | Base64/hex encoded data piped to external services, curl/wget/nc exfil, DNS tunneling, sensitive file piping | Critical |
| **PromptManipulation** | ASI02 | Prompt injection, jailbreak attempts, system prompt override | Critical |
| **HallucinationChain** | ASI01 | Speculation promoted to "fact" across messages | Critical |
| **MemoryPoisoning** | ASI03 | Attempts to corrupt agent memory or inject false context | High |
| **UnauthorizedAccess** | MCP05 | Privilege escalation, unauthorized resource access | High |
| **ShadowServer** | MCP09 | Communication with undeclared external services | High |
| **InformationFlow** | MCP06/10 | Data flowing between unauthorized agent pairs | High |
| **PhantomCitation** | ASI06 | Fabricated URLs, DOIs, arxiv IDs, paper references | High |
| **ShorthandEmergence** | ASI07 | "Process order" becomes "PO" — agents developing private language | High |
| **UncertaintyPropagation** | ASI08 | "partial results" silently becomes "complete results" downstream | High |
| **EntropyCovertChannel** | ASI06 | High-entropy strings that may encode hidden messages (Shannon entropy analysis, threshold-adjusted per alphabet) | Medium-High |
| **GovernanceGap** | ASI10 | Unauthorized deployment, fund transfer, data deletion without approval | High |
| **ToolCallFrequency** | MCP09 | Unusual spike or pattern in tool invocations | Medium |
| **ToolDescriptionDivergence** | MCP03 | Tool description changed between calls | Critical |

### 6 Core Detectors

| Detector | What It Catches | Severity |
|----------|-----------------|----------|
| **BlankResponse** | Agent returns empty or whitespace-only response | Critical |
| **TruncatedOutput** | Response cut off mid-sentence (with 200-char minimum guard) | High |
| **RepetitionLoop** | Agent stuck in a loop, repeating the same output | High |
| **ContextCollapse** | Topic suddenly changes; structured data exemption for JSON/YAML | High |
| **IncompleteCode** | Code blocks missing closing brackets or truncated | Medium |
| **WaitingForDescription** | Agent returns placeholder text instead of real content | Medium |

---

## Claude Code Integration

InsAIts provides deep integration with Claude Code through a **PreToolUse + PostToolUse hook system**:

### Hook Runner (Lightweight, <1.5s response time)

```bash
# In .claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "command": "python InsAIts-SDK/scripts/insaits_hook_runner.py",
      "timeout": 10000
    }],
    "PostToolUse": [{
      "command": "python InsAIts-SDK/scripts/insaits_hook_runner.py",
      "timeout": 10000
    }]
  }
}
```

### What the Hook Does

| Phase | Action |
|-------|--------|
| **PreToolUse** | Scans tool input for credential exposure, prompt injection, sensitive file access. Can **block** dangerous tool calls (returns `permissionDecision: deny`). |
| **PostToolUse** | Scans tool output through all 17 security adapters + 6 core detectors. Logs to audit trail. |

### Hook Features (9 toggleable)

| Feature | What It Does |
|---------|-------------|
| **Response Awareness** | Periodic context injection reminding Claude of monitoring |
| **Task Anchor** | Maintains user intent across long conversations; injects anchor at tool boundaries |
| **Loop Detection** | Detects when Claude repeats the same tool call 3+ times |
| **Surrender Detection** | Catches when Claude gives up instead of solving the problem |
| **Sensitive File Access** | Alerts when accessing .env, credentials, private keys |
| **Monitoring Gap** | Detects 30+ second gaps with no tool call activity |
| **Write Tracking** | Tracks file modifications; detects file thrashing (5+ writes to same file in 60s) |
| **Frustration Detection** | Identifies patterns where Claude is stuck or frustrated |
| **Ask User Intervention** | At Persistence Engine level 4+, suggests/forces human-in-the-loop |

### Persistence Engine (5-Level Escalation)

When Claude repeatedly fails at a task, the Persistence Engine escalates automatically:

| Level | Action | What Happens |
|-------|--------|-------------|
| 1 | NUDGE | Gentle hint to reconsider approach |
| 2 | REDIRECT | Suggest alternative strategy |
| 3 | DECOMPOSE | Break the task into smaller steps |
| 4 | ESCALATE | Warn: "Consider asking the user" (suggest mode) |
| 5 | CIRCUIT_BREAK | **Block the tool call** with `permissionDecision: deny` |

### Subagent Attribution

Every tool call is attributed to the correct agent identity:
- Direct tools: `claude:Bash`, `claude:Edit`, `claude:Read`, etc.
- Subagents: `subagent:Explore`, `subagent:Plan`, `subagent:general-purpose`
- Parallel agent tracking: multiple concurrent subagents tracked independently

---

## Web Dashboard (16+ Panels)

Real-time web dashboard on `http://localhost:5001`:

```bash
python insaits_web_dashboard.py
```

### Dashboard Panels

| Panel | What It Shows |
|-------|-------------|
| **Threat Index Ring** | Overall threat assessment (0-100%) |
| **Blast Radius Ring** | Impact scope of detected anomalies |
| **Intervention Rate Ring** | Percentage of tool calls requiring intervention |
| **Live Feed** | Real-time anomaly stream with severity color coding |
| **Agent Scores** | Per-agent trust scores and anomaly rates |
| **Anomaly Distribution** | Breakdown by category: Security, Hallucination, Semantic, Communication, Model |
| **Circuit Breakers** | Per-agent circuit breaker states (CLOSED/OPEN/HALF_OPEN) |
| **Tool Call Inspector** | Drill-down into every tool invocation with timestamps, agents, status |
| **OWASP Security** | Security events mapped to OWASP MCP Top 10 + Agentic AI Top 10 codes |
| **Message History** | Full message history with filters and search |
| **Task Anchor** | Current user anchor + drift monitoring |
| **Persistence Engine** | 5-level escalation state per agent |
| **Token Usage** | Input/output/cache token counts, Opus cost estimate, rate/min |
| **Session Comparison** | Historical session summaries for trend analysis |
| **Config Toggles** | Enable/disable any of 18 detectors + 9 features live |
| **Task Anchor Editor** | Edit the user intent anchor from the dashboard |

### Activity Status

| Status | Condition | Color |
|--------|-----------|-------|
| LIVE | <30s since last tool call | Green |
| IDLE | 30s-5min since last tool call | Amber |
| STOPPED | >5min since last tool call | Red |

### Transcript Tailer

Background daemon that reads Claude Code's session transcript every 10 seconds:
- Extracts subagent tool calls (Layer 2 visibility)
- Extracts token usage (`message.usage` from API responses)
- Writes to audit log for dashboard visualization
- Disable with `--no-tailer` flag

---

## Terminal Dashboard (TUI)

For VS Code split terminal:

```bash
pip install insa-its[dashboard]
insaits-dashboard
```

---

## V3: Active Intervention

### Intervention Engine

```python
engine = monitor.enable_interventions()

# Human-in-the-loop for critical anomalies
def review_critical(message, result, context):
    return True  # Allow, or False to quarantine

engine.register_hitl_callback(review_critical)
engine.register_reroute("risky_agent", "backup_agent")

outcome = monitor.intervene(message, result["monitor_result"])
```

| Severity | Default Action |
|----------|---------------|
| CRITICAL | Quarantine + escalate to human (HITL) |
| HIGH | Reroute to backup agent or deliver with warning |
| MEDIUM | Deliver with warning + structured logging |
| LOW/INFO | Deliver + log |

### Circuit Breaker

```python
result = monitor.send_message("text", "agent1", "agent2", "gpt-4o")
# If agent1's anomaly rate exceeds threshold: result = {"error": "circuit_open", ...}

state = monitor.get_circuit_breaker_state("agent1")
# {"state": "closed", "anomaly_rate": 0.15, "window_size": 20}
```

### Tamper-Evident Audit Log

SHA-256 hash chain for regulatory compliance:

```python
monitor.enable_audit("./audit_trail.jsonl")
assert monitor.verify_audit_integrity()  # Detects any tampering
```

### Prometheus Metrics

```python
metrics_text = monitor.get_metrics()
# insaits_messages_total, insaits_anomalies_total{severity="..."},
# insaits_processing_duration_ms (histogram)
```

---

## Hallucination Detection

Five independent detection subsystems:

```python
monitor = insAItsMonitor()
monitor.enable_fact_tracking(True)

# Cross-agent fact contradictions
monitor.send_message("The project costs 1000 dollars.", "agent_a", llm_id="gpt-4o")
result = monitor.send_message("The project costs 5000 dollars.", "agent_b", llm_id="claude-3.5")
# result["anomalies"] includes FACT_CONTRADICTION (critical)

# Phantom citation detection
citations = monitor.detect_phantom_citations(
    "According to Smith et al. (2030), see https://fake-journal.xyz/paper"
)

# Source grounding
monitor.set_source_documents(["Your reference docs..."], auto_check=True)
result = monitor.check_grounding("AI response to verify")

# Full hallucination health report
summary = monitor.get_hallucination_summary()
```

| Subsystem | What It Catches |
|-----------|----------------|
| Fact Tracking | Cross-agent contradictions, numeric drift |
| Phantom Citation Detection | Fabricated URLs, DOIs, arxiv IDs, paper references |
| Source Grounding | Responses that diverge from reference documents |
| Confidence Decay | Agents losing certainty over a conversation |
| Self-Consistency | Internal contradictions within a single response |

---

## Integrations

### LangChain
```python
from insa_its.integrations import LangChainMonitor
monitor = LangChainMonitor()
monitored_chain = monitor.wrap_chain(your_chain, "MyAgent",
    workflow_id="order-123", halt_on_critical=True)
```

### CrewAI
```python
from insa_its.integrations import CrewAIMonitor
monitor = CrewAIMonitor()
monitored_crew = monitor.wrap_crew(your_crew)
```

### LangGraph
```python
from insa_its.integrations import LangGraphMonitor
monitor = LangGraphMonitor()
monitored_graph = monitor.wrap_graph(your_graph)
```

### Slack / Notion / Airtable
```python
from insa_its.integrations import SlackNotifier, NotionExporter, AirtableExporter
slack = SlackNotifier(webhook_url="https://hooks.slack.com/...")
slack.send_alert(anomaly)
```

---

## Stealth Mode

For red-team exercises and compliance audits where agents may adapt under observation:

```bash
export INSAITS_STEALTH=1
```

| Feature | Behavior |
|---------|----------|
| Opaque interventions | Anomaly metadata hidden from agent responses |
| Random checkpoints | Deep inspection at non-deterministic intervals |
| HITL escalation | CRITICAL findings require human approval |
| Silent audit trail | Full logging with no observable side effects |

---

## Configuration

All detectors and features are toggleable via `.insaits_config.json`:

```json
{
  "detectors": {
    "credential_exposure": true,
    "prompt_injection": true,
    "tool_poisoning": true,
    "data_exfiltration": true,
    "exfiltration_pattern": true,
    "entropy_covert_channel": true,
    "rogue_agent": true,
    "unauthorized_access": true,
    "context_collapse": true,
    "truncated_output": true,
    "hallucination_chain": true,
    "shorthand_emergence": true,
    "uncertainty_propagation": true,
    "governance_gap": true,
    "memory_poisoning": true,
    "shadow_server": true,
    "information_flow": true,
    "phantom_citation": true
  },
  "features": {
    "response_awareness": true,
    "task_anchor": true,
    "loop_detection": true,
    "surrender_detection": true,
    "sensitive_file_access": true,
    "monitoring_gap": true,
    "write_tracking": true,
    "frustration_detection": true,
    "ask_user_intervention": true
  },
  "response_awareness_interval": 8
}
```

Toggle any detector or feature from the web dashboard's Config panel without restarting.

---

## Open-Core Model

The core SDK is **Apache 2.0 open source**. Premium features ship with `pip install insa-its`.

| Feature | License | Status |
|---------|---------|--------|
| All 23 anomaly detectors (17 adapters + 6 core) | Apache 2.0 | Open |
| Hallucination detection (5 subsystems) | Apache 2.0 | Open |
| Circuit breaker, interventions, audit, metrics | Apache 2.0 | Open |
| Security detectors (OWASP MCP + Agentic AI Top 10) | Apache 2.0 | Open |
| CVE signature matching | Apache 2.0 | Open |
| Claude Code hook system (PreToolUse + PostToolUse) | Apache 2.0 | Open |
| Web dashboard (16+ panels) + Terminal dashboard | Apache 2.0 | Open |
| Persistence Engine (5-level escalation) | Apache 2.0 | Open |
| All integrations (LangChain, CrewAI, LangGraph, Slack, Notion, Airtable) | Apache 2.0 | Open |
| Local embeddings + Ollama | Apache 2.0 | Open |
| **AI Lineage Oracle** (compliance) | Proprietary | Premium |
| **Edge/Hybrid Swarm Router** | Proprietary | Premium |
| **Decipher Engine** (AI-to-Human translation) | Proprietary | Premium |
| **Adaptive jargon dictionaries** | Proprietary | Premium |

---

## Pricing

| Tier | What You Get | Price |
|------|--------------|-------|
| **Free** | 100 msgs/day, all open-source features | **$0** |
| **Starter** | 500 msgs/day, cloud features, email support | **$9.90/month** |
| **Pro** | Unlimited messages, premium detectors, priority support | **$79/month** |
| **Enterprise** | Everything + compliance exports, SLA, self-hosted | **Custom** |

> Free tier works without an API key. Just `pip install insa-its` and start monitoring.

### 100 FREE LIFETIME Keys

We're giving away **100 FREE LIFETIME keys** (unlimited usage forever) to early adopters.

**How to claim:** Email **info@yuyai.pro** with your use case (1-2 sentences). First 100 get lifetime access.

---

## Architecture

```
Your Multi-Agent System                    InsAIts V3.1.6 Security Layer
         |                                          |
         |-- user query -----> set_anchor() ------> |
         |-- source docs ----> set_source_documents() |
         |                                          |
         |-- message --------> Circuit Breaker ---> |
         |                     (is agent blocked?)   |
         |                                          |-- Embedding generation (local)
         |                                          |-- Pattern analysis
         |                                          |-- 17 Security adapters (OWASP MCP/ASI)
         |                                          |-- 6 Core detectors
         |                                          |-- Hallucination suite (5 subsystems)
         |                                          |-- Exfiltration pattern analysis
         |                                          |-- Shannon entropy (covert channels)
         |                                          |-- Persistence Engine (5-level)
         |                                          |
         |                                          |-- Build MonitorResult
         |                                          |-- Circuit breaker state update
         |                                          |-- Structured logging + metrics
         |                                          |-- Audit log (SHA-256 hash chain)
         |                                          |
         |<-- MonitorResult (should_halt/alert) ----|
         |                                          |
         |-- intervene() ---> Intervention Engine   |
         |                    CRITICAL: quarantine   |
         |                    HIGH: reroute/warn     |
         |                    MEDIUM: warn + log     |
         |                    LOW: deliver + log     |
```

**Privacy First:**
- All detection and intervention runs locally
- No message content sent to cloud
- Audit logs store hashes, never raw content
- API keys hashed before storage
- GDPR-ready

---

## Use Cases

| Industry | Problem Solved |
|----------|----------------|
| **E-Commerce** | Order bots losing context mid-transaction |
| **Customer Service** | Support agents developing incomprehensible shorthand |
| **Finance** | Analysis pipelines hallucinating metrics, contradicting numbers |
| **Healthcare** | Critical multi-agent systems where errors have consequences |
| **Research** | Ensuring scientific integrity, catching fabricated citations |
| **Legal** | AI-generated documents with phantom references |
| **Security** | Red-team AI exercises, compliance audits, data exfiltration detection |
| **DevOps** | Monitoring Claude Code / Copilot tool calls in CI/CD pipelines |

---

## Documentation

| Resource | Link |
|----------|------|
| Installation Guide | [installation_guide.md](installation_guide.md) |
| API Reference | [insaits-api.onrender.com/docs](https://insaits-api.onrender.com/docs) |
| Privacy Policy | [PRIVACY_POLICY.md](../PRIVACY_POLICY.md) |
| Terms of Service | [TERMS_OF_SERVICE.md](TERMS_OF_SERVICE.md) |

---

## Support

- **Email:** info@yuyai.pro
- **GitHub Issues:** [Report a bug](https://github.com/Nomadu27/InsAIts/issues)
- **API Status:** [insaits-api.onrender.com](https://insaits-api.onrender.com)

---

## License

**Open-Core Model:**
- Core SDK: [Apache License 2.0](LICENSE) - free to use, modify, and distribute
- Premium features (`insa_its/premium/`): Proprietary - included via `pip install insa-its`

---

<p align="center">
<strong>InsAIts V3.1.6 - Making Multi-Agent AI Trustworthy, Auditable, and Secure</strong><br>
<em>17 security adapters. 6 core detectors. OWASP MCP + Agentic AI Top 10 coverage. Shannon entropy analysis. Persistence Engine. 16+ dashboard panels. 1115+ tests passing.</em><br><br>
<strong>100 FREE LIFETIME keys for early adopters: info@yuyai.pro</strong>
</p>
