convez.ai
MCP Server
Shaugato

find-evil

Shaugato/find-evil

Ver no GitHub
InicialPluginScore · de 0 a 100

Stigmergy - autonomous DFIR through stigmergic swarm intelligence. Math decides, a signed ledger records, the LLM only explains. (SANS Find Evil! hackathon - Custom MCP Server.)

Instalação

$npx convez-ai Shaugato/find-evil

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Stigmergy

Stigmergy is a local-first autonomous Security Operations Center platform for defensive detection, evidence fusion, and safe-mode response automation. It ingests synthetic or owned telemetry, correlates evidence with deterministic Dempster-Shafer fusion, records every decision in a cryptographically verified ledger, and can emit CACAO, STIX, and OCSF artifacts for interoperability.

The hot path is deterministic and does not depend on an LLM. LLM-backed narrator and fractal pivot agents run out of band after the mathematical decision has already been written to the ledger.

License: MIT (see LICENSE).

SANS "Find Evil!" Hackathon

This repository is a Find Evil! submission built as a Custom MCP Server (Approach #2): 62 typed, schema-validated MCP tools with reference-resolved exhibit IDs and server-side output parsing — there is no execute_shell_cmd, so the agent cannot run arbitrary commands. Math decides, the ledger records, the LLM only explains.

The eight required deliverables live under docs/hackathon/:

#DeliverableLocation
1Code repository (MIT)this repo
2Demo video (≤5 min)▶ Watch on YouTube · script
3Architecture diagramarchitecture-diagram.md
4Project descriptionproject-description.md
5Dataset documentationdataset.md
6Accuracy reportaccuracy-report.md
7Try-it-out instructionstry-it-out.md · Docker · installer
8Agent execution logsexecution-logs/

Fastest paths to evaluate: ▶ watch the 5-minute demo (live ROCBA carve + self-correction + the MCP guardrail), the live companion site → https://web-eight-sage-34.vercel.app (zero install — architecture explainer + real-run replay viewer), the Docker stack (deploy/, one command), or the one-click launcher (installer/).

What This Repository Contains

  • Python package under src/findevil
  • Systemd unit files and service configs under etc/
  • Bootstrap, key generation, validation, and utility scripts under scripts/
  • Unit, integration, benchmark, and contract tests under tests/
  • Public product documentation:
    • README.md for setup and daily usage
    • PLATFORM.md for architecture and subsystem behavior
    • VALIDATION_REPORT.md for the current validation evidence

This public repository intentionally excludes local runtime data, private keys, model files, forensic evidence, extracted research drafts, rendered analysis artifacts, and workstation-specific UI design sources.

Safety Scope

Stigmergy is defensive infrastructure. The validation harness uses locally generated JSON telemetry published to local NATS/Valkey services. It does not require real malware, exploit traffic, or unauthorized access to any external system.

Requirements

  • Ubuntu 24.04 on WSL2 or bare-metal Linux
  • Python 3.12
  • Valkey
  • NATS
  • OpenTelemetry Collector
  • Optional but recommended forensic tools:
    • YARA
    • Zeek
    • TShark
    • Sleuth Kit
    • Volatility 3
    • Plaso
    • bulk_extractor
  • Optional local inference server:
    • llama-cpp-python serving an OpenAI-compatible API on 127.0.0.1:8080

Quick Start

Clone the repository into the expected runtime location:

sudo install -d -m 0755 -o "$USER" -g "$USER" /opt/findevil
git clone https://github.com/<your-user>/<your-repo>.git /opt/findevil/repo
cd /opt/findevil/repo

Run the bootstrap script:

bash scripts/bootstrap.sh

Create or review the environment file:

sudo install -d -m 0750 -o findevil -g findevil /opt/findevil/etc
sudo cp -n etc/.env.example /opt/findevil/etc/.env
sudoedit /opt/findevil/etc/.env

Install and start the service units:

sudo cp etc/systemd/*.service etc/systemd/*.timer etc/systemd/*.target /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now findevil.target

Verify the platform:

/opt/findevil/venv/bin/findevil verify
/opt/findevil/venv/bin/findevil status
/opt/findevil/venv/bin/findevil tip

Run the test suite:

cd /opt/findevil/repo
/opt/findevil/venv/bin/python -m pytest tests/ -q

Main Services

ServicePurpose
findevil-ingest / findevil-bytewaxNATS/ZMQ telemetry ingest, parsing, D-S fusion, threshold evaluation
findevil-cacaoSafe-mode CACAO playbook generation and execution logging
findevil-mcpMCP blackboard resources and forensic tool shims
findevil-narratorOut-of-band prosecutor/defense/judge explanation path
findevil-watcherFractal pivot agent watcher with depth/width budgets
findevil-dashboardFastAPI dashboard and live SSE views
findevil-verify.timerScheduled ledger chain verification
findevil-otelOpenTelemetry collector

Useful Commands

findevil verify
findevil tip
findevil recent -n 20
findevil list-tools
findevil ingest
findevil cacao
findevil mcp           # custom MCP server over HTTP (streamable-http, :9310/mcp)
findevil mcp --stdio   # …or over stdio for Claude Desktop / Claude Code
findevil narrator
findevil watcher
findevil dashboard

Connect any MCP client (Claude Desktop / Claude Code / OpenClaw / Cursor / Cline / Aider) to the typed forensic tool catalog — the Approach #2 guardrail in your own client:

claude mcp add stigmergy -- "$(pwd)/.venv/bin/python" -m findevil.mcp_server

See Option E in try-it-out.md for the per-client configs (Claude Desktop, OpenClaw, generic) and the HTTP/URL form — you should see ~64 typed tools and no execute_shell.

Run the public validation harness:

/opt/findevil/venv/bin/python scripts/whitehat_validation.py
findevil verify

Dashboard

When findevil-dashboard.service is running, open:

http://127.0.0.1:9400/

Key endpoints:

/api/health
/api/pheromones
/api/ledger/tip
/api/cacao/recent
/sse/pheromones

Documentation

  • PLATFORM.md explains how the platform is assembled.
  • VALIDATION_REPORT.md records the current validation status and known gaps.
  • docs/runbook.md contains operational notes.

Public Release Notes

Do not commit:

  • /opt/findevil/data/ledger/*.sqlite*
  • /opt/findevil/etc/keys/*
  • /opt/findevil/data/models/*
  • forensic evidence, generated captures, private logs, or local screenshots
  • private research drafts or extracted document artifacts

The repository is intended to publish the product implementation and reproducible validation workflow, not local evidence, credentials, model weights, or private workstation artifacts.

Ver o original no GitHub

Bom para

Relacionados