Skip to content

GEMINI.md

Latest commit

 

History

History
115 lines (87 loc) · 4.37 KB

GEMINI.md

File metadata and controls

115 lines (87 loc) · 4.37 KB
Raw

CyberDiagram Security Audit Agent

Project Overview

The Security Audit Specialist Agent is an autonomous system designed to perform comprehensive penetration testing and vulnerability assessments. It leverages the Claude Agent SDK and Model Context Protocol (MCP) to integrate professional security tools (nmap, dirbuster, metasploit) with AI-driven decision-making.

Key Features

  • Autonomous Reconnaissance: Network scanning and service enumeration.
  • Vulnerability Research: Integration with Exploit-DB and Metasploit.
  • Real-time Monitoring: WebSocket-based dashboard for tracking scans and findings.
  • Compliance & Reporting: SOC2/ISO 27001 compliant audit logging and automated Markdown reporting.
  • Safety & Control: Strict target authorization and validation to ensure legal compliance.

Tech Stack

  • Runtime: Node.js (v18+)
  • Language: TypeScript
  • AI Core: @anthropic-ai/claude-agent-sdk
  • Database: SQLite (better-sqlite3)
  • API/Monitoring: Express, Socket.io
  • Dashboard: React (Vite), Recharts, Tailwind CSS (implied/likely), Socket.io-client

Architecture

The system follows a modular architecture:

  1. Agent Core (src/index.ts): The central brain using Claude to orchestrate tools.
  2. MCP Servers (src/mcp/): Wrappers for external tools (nmap, etc.) exposing them as AI-callable functions.
  3. Database Layer (src/database/): SQLite storage for scan results, vulnerabilities, and logs.
  4. Monitoring Server (src/monitoring/): WebSocket server broadcasting real-time events.
  5. Dashboard (dashboard/): A separate React application for visualizing the monitoring data.

Getting Started

Prerequisites

  • Node.js 18+
  • Nmap, Dirb, Metasploit Framework, ExploitDB (installed on the host system)
  • Anthropic API Key

Configuration

  1. Copy .env.example to .env.
  2. CRITICAL: Configure AUTHORIZED_TARGETS and ANTHROPIC_API_KEY. 
    AUTHORIZED_TARGETS=10.10.10.3,192.168.1.0/24
ANTHROPIC_API_KEY=sk-...

Development Workflow

1. Agent Development

The agent is located in the root directory.

  • Install Dependencies: npm install
  • Run in Development (TSX): 
    npm run dev -- <target> <scan-type>
# Example: npm run dev -- 10.10.10.3 quick
  • Build for Production: npm run build
  • Run Production Build: npm start <target> <scan-type>

2. Monitoring System

The monitoring server runs independently to receive and broadcast events.

  • Start Server: npm run monitor
  • The server listens on port 3000 (default) and provides a WebSocket endpoint and REST API.

3. Dashboard Development

The dashboard is a separate React project in the dashboard/ folder.

  • Navigate: cd dashboard
  • Install Dependencies: npm install
  • Run Dev Server: npm run dev (Starts Vite at http://localhost:5173)
  • Build: npm run build

Key Commands Reference

Command Description
npm run dev -- <args> Run the agent with tsx (no build required).
npm run build Compile TypeScript to dist/.
npm start <args> Run the compiled agent.
npm run monitor Start the monitoring WebSocket/API server.
npm run check-report -- <id> Validate a generated report.
npm run clean Remove dist/ directory.

Directory Structure

  • src/ - Agent source code.
    • database/ - SQLite database interactions.
    • logger/ - Audit logging implementation.
    • mcp/ - Tool integrations (MCP servers).
    • monitoring/ - Monitoring server logic.
    • report/ - Report generation and validation.
    • utils/ - Authorization and helper functions.
  • dashboard/ - React frontend application.
  • data/ - SQLite database storage (audit.db).
  • logs/ - JSON Lines audit logs.
  • reports/ - Generated Markdown reports.

Conventions

  • Authorization: All scanning actions MUST be validated against AUTHORIZED_TARGETS.
  • Logging: All security-relevant actions are logged to both the database and logs/ directory for compliance.
  • Typing: Strict TypeScript usage is enforced (strict: true in tsconfig.json).
  • Safety: The agent is designed to be non-destructive. It validates vulnerabilities but does not execute harmful exploits by default.