Agent Zero

Real-time credential leak detection and remediation for Slack.

Agent Zero is an autonomous compliance guardian for your Slack workspace. It actively monitors channels for leaked secrets, API keys, passwords, and sensitive PII, instantly flagging risks to administrators while preserving team workflows.

Features

• Real-time monitoring: Employs hybrid regex and AI semantic detection to catch leaked credentials immediately.

• Calm UX dashboard: A beautiful, soothing pastel design to visualize and monitor compliance metrics without alert fatigue.

• Mark as Safe: False positive learning engine lets users dismiss alerts and teach the system to ignore harmless patterns.

• 15+ credential patterns: Natively detects plaintext passwords, API tokens, AWS keys, Stripe keys, credit cards, SSH keys, database connection strings, and more.

• Smart deduplication: Consolidates overlapping regex matches into single alerts (no duplicate notifications).

• Slash commands: Interact directly via Slack using /audit-scan, /audit-report, /audit-search, and /audit-status.

• Multi-Provider AI Router: High-availability AI validation across Gemini, OpenRouter, Groq, and GitHub Models to drastically reduce false positives.

• MCP Server (SSE): Native Model Context Protocol server integration allowing autonomous agentic workflows and tool execution.

• PDF compliance report generation: Automated, boardroom-ready exports of your workspace's security posture.

• Docker support: Fully containerized and production-ready.

• Comprehensive test suite: Backed by a 23-check automated verification suite ensuring unbreakable reliability.

Related MCP server: @1claw/mcp

Tech Stack

• Core: Python 3.11

• Integrations: Slack Bolt Framework (HTTP Events API), Model Context Protocol (FastMCP)

• Web Dashboard: Flask, HTML5, CSS3, Chart.js

• AI Integration: Google GenAI, Requests (for OpenAI-compatible endpoints)

• Storage: JSONL (Append-only)

• Deployment: Docker, Docker Compose, PythonAnywhere

Getting Started

1. Clone the repository:

   git clone git@github.com:Abdulrahman-Alfeqy/AgentZero.git
   cd AgentZero

2. Configure Environment: Copy the example config and fill in your Slack and API keys.

   cp .env.example .env

3. Install Dependencies:

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

4. Run Agent Zero:

   python main.py

Environment Variables

Dashboard Access

Once Agent Zero is running, you can access the compliance dashboard via your browser:

• URL: http://localhost:5000/dashboard

• Username: admin (or your custom DASHBOARD_USERNAME)

• Password: agentzero (or your custom DASHBOARD_PASSWORD)

For cloud deployment, ensure DASHBOARD_HOST=0.0.0.0 and PORT=5000 are set.

Architecture Overview

flowchart TD
    User(("👤 Slack User"))
    Channel["💬 Slack Channel"]
    Alert["🔴 Private Ephemeral Alert<br/>Visible ONLY to Sender"]
    Agent["🛡️ Agent Zero\nSlack Bolt (HTTP Events API)"]

    subgraph DE ["🛡️ Detection Engine"]
        direction LR
        Regex["📝 Regex<br/>15+ Patterns"]
        Entropy["📊 Entropy<br/>Excludes UUIDs/Hashes"]
        AIRouter["🧠 AI Router<br/>Gemini · OpenRouter · Groq · GitHub"]
        Entropy -- "🟢 Automatic Failover<br/>AI Router with 4 LLMs" --> AIRouter
    end

    Admin["🔵 Admin DM<br/>HIGH Severity Escalation"]
    Compliance["👮 Compliance Officer"]
    MCP["🔌 MCP Server (SSE)"]
    PDF["📄 PDF Reports<br/>/audit-report"]
    Log[("🗄️ Incident Log<br/>Masked · JSONL")]
    Dash["📈 Dashboard<br/>Flask + Chart.js"]

    User -- "Message" --> Channel
    Channel -- "Event" --> Agent
    Agent -- "Analyse Text" --> DE

    Agent == " " ==> Alert
    Alert == " " ==> User

    DE -- "Store (Masked)" --> Log
    Log --> Dash
    Dash --> Compliance

    DE --> Admin
    Admin --> Compliance

    MCP --> DE
    MCP --> PDF
    MCP --> Log

    classDef default fill:#f5f5fc,stroke:#b1b1e4,stroke-width:1px,color:#333
    classDef yellowBox fill:#fdfde6,stroke:#d4d4a3,stroke-width:1px,color:#333
    classDef alertBox fill:#f0f0f0,stroke:#d3d3d3,stroke-width:1px,color:#333

    class User,Log fill:#f5f5fc,stroke:#9b59b6,stroke-width:1.5px
    class DE yellowBox
    class Alert alertBox

Deploying to PythonAnywhere

PythonAnywhere's free tier provides exactly one WSGI web app with a public HTTPS domain. Agent Zero is compatible because it is structured as a single Flask app object after the HTTP Events API migration.

WSGI Configuration File

In your PythonAnywhere dashboard, go to Web → WSGI configuration file and replace the default content with:

import sys
import os

# Point to your project directory
sys.path.insert(0, '/home/<your-username>/AgentZero')

# Load environment variables from .env
from dotenv import load_dotenv
load_dotenv('/home/<your-username>/AgentZero/.env')

# Import the consolidated Flask app
from main import flask_app as application

Slack Event Subscriptions URL

In your Slack App settings, go to Event Subscriptions → Request URL and set:

https://<your-username>.pythonanywhere.com/slack/events

Slack will send a url_verification challenge — Bolt's adapter handles it automatically. Wait for the green tick before saving.

Bot Events to Subscribe

Under Event Subscriptions → Subscribe to bot events, add:

Outbound API Allowlist

PythonAnywhere's free tier restricts outbound HTTP to an allowlist. Add these domains via Account → Whitelist a new domain for AI provider support:

If any domain is not allowlisted, that AI provider is skipped silently and the fallback chain continues. The app never crashes on a missing provider — it degrades to regex-only detection, exactly as documented for a blank API key.

Persistent Storage Note

PythonAnywhere free tier does provide persistent disk storage, so incidents.jsonl and generated PDFs survive restarts (unlike Render's free tier).

Roadmap

• Migrate from JSONL to a scalable relational database (SQLite/PostgreSQL) for large workspace querying.

• Introduce WebSockets for real-time, zero-refresh dashboard updates.

• Support full Slack OAuth flow for multi-workspace public distribution.

License

This project is licensed under the MIT License. See the LICENSE file for details.