<!-- 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-1115%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="docs/assets/insaits-live-demo.mp4">Watch the full live demo video</a>
</p>

---

## 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
```

For local embeddings (recommended):
```bash
pip install insa-its[full]
```

For the live terminal dashboard:
```bash
pip install insa-its[dashboard]
```

---

## 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>
