Skip to main content
Glama
MIRAI Intelligence & Research MCP

MIRAI Intelligence & Research MCP

by Tarant336
README.md
❤️ Support My Work

If you find my projects useful, please consider supporting me with a donation.

Your support helps me maintain my projects, improve existing features, and develop more useful open-source tools.

Every donation, no matter how small, is greatly appreciated. Thank you for your kindness and support!

💰 Donate via USDT (TRC20)
Network: TRON (TRC20)
Currency: USDT
Wallet Address: TENRVUreWCFdGzceVsG6Lwr2EQtKytQQ2b

Thank you for supporting open-source development! ❤️
====================================================================================================
# MIRAI Intelligence & Research MCP

An autonomous, evidence-driven research and software-engineering platform implemented as a
**Model Context Protocol (MCP) server** in **TypeScript**.

The platform unifies three core intelligence engines on top of one shared evidence layer:

- **Engine A — Technical Software Engineering Intelligence** (`software-engineering`)
- **Engine B — Botnet, Mirai & Malware Intelligence** (`malware-intelligence`)
- **Engine C — Exploit & Vulnerability Intelligence** (`exploit-intelligence`)
- **Engine D — Zero-Day Research** (`zero-day-research`)

plus supporting engines: `attack-methods`, `anti-ddos`, `firmware-intelligence`,
`network-forensics`, `knowledge-and-evidence`, `datasets`, `multi-agent`, `platform`,
**and `skills` — a versioned library of reusable techniques**.

---

## 1. Status

| Item | Result |
|---|---|
| Registered engines | **13** |
| Registered MCP tools | **113** |
| MCP prompts | **6** |
| MCP resources | **2** |
| Multi-agent roles / workstreams | **23 / 23** |
| Skills in library | **36** |
| Typecheck (`tsc --noEmit`) | 0 errors |
| Build (`tsc`) | success |
| Test suite (vitest) | **178/178 pass** (12 files) |
| End-to-end stdio check | success (113 tools, 6 prompts) |

---

## 2. Install and run

```bash
npm install
npm run build          # compile to dist/
npm start              # run the MCP server over stdio
npm run dev            # development mode (tsx watch)
npm run verify         # typecheck + full test suite
npm run stdio-check    # real JSON-RPC handshake over stdin/stdout
npm run inspector      # open MCP Inspector
```

### Register with an MCP client (example JSON config)

```json
{
  "mcpServers": {
    "mirai-intelligence": {
      "command": "node",
      "args": ["/absolute/path/to/mirai-mcp/dist/index.js"],
      "env": {
        "MIRAI_WORKSPACE": "/absolute/path/to/your/workspace",
        "MIRAI_LOG_LEVEL": "info"
      }
    }
  }
}
```

---

## 3. Configuration

Configuration is merged in this order: `MIRAI_*` environment variables → `mirai.config.json`
(or `MIRAI_CONFIG`) → defaults.

| Variable | Default | Meaning |
|---|---|---|
| `MIRAI_WORKSPACE` | `process.cwd()` | Directory boundary for reads/writes |
| `MIRAI_DATA_DIR` | `~/.mirai-mcp` | Knowledge base storage location |
| `MIRAI_LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error` |
| `MIRAI_ALLOW_PUBLIC_FETCH` | `true` | Allow public network access (read-only) |
| `MIRAI_ALLOW_ISOLATED_EXEC` | `true` | Allow command execution inside the isolated sandbox |
| `MIRAI_EXEC_TIMEOUT_MS` | `120000` | Hard timeout per sandboxed command |
| `MIRAI_EXEC_MAX_OUTPUT_BYTES` | `4194304` | Output size cap |
| `MIRAI_MAX_ARTIFACT_BYTES` | `268435456` | Cap for artifacts read into memory |
| `MIRAI_LAB_TOKEN` | *(unset)* | Required token for active lab testing |
| `MIRAI_TRANSPORT` | `stdio` | `stdio` (HTTP not enabled) |

> `allowOffensiveOps` is **always `false`** and cannot be enabled through configuration (hard-coded
> in [config/index.ts](src/config/index.ts)).

### Dependency diagnostics

The platform **never assumes** external tools are installed. Every dependency is probed
(read-only — it never downloads or installs anything) and reported as one of:

`AVAILABLE` · `MISSING` · `VERSION_UNSUPPORTED` · `CONFIGURATION_ERROR` · `NOT_REQUIRED`

Probed dependencies: **GCC, Clang, AFL++, Honggfuzz, QEMU ARM/MIPS, Binwalk, 7-Zip, objdump,
readelf, strings, nm, Radare2, Ghidra, Git.** (See
[dependencies.ts](src/core/dependencies.ts).)

- The `dependency_diagnostics` tool (engine `platform`) lists each dependency's status; pass
  `required: ["aflplusplus", ...]` to mark dependencies your workflow needs.
- `environment_report` embeds the same probe results.
- A tool that depends on an unavailable dependency **throws `TOOL_MISSING`** with per-dependency
  install hints — it never returns a fake success.
- `node scripts/dependency-report.mjs` writes host status to `scripts/_dependency-report.json`
  (does not fail the build; missing dependencies are recorded as **BLOCKED**, never PASS).

---

## 4. Architecture

```
src/
├── index.ts                     # entry point: registers all engines + starts the server
├── config/index.ts              # merged configuration, safe defaults
├── core/
│   ├── server.ts                # MCP SDK adapter: policy gate → handler → evidence
│   ├── registry.ts              # ToolRegistry: unique names, policy pre-screening
│   ├── tool.ts                  # EngineModule / ToolDefinition / ToolContext
│   ├── errors.ts                # MiraiError with actionable `code` + `hint`
│   ├── logger.ts                # structured logging over stderr (keeps stdio clean)
│   └── environment.ts           # Phase 1 — environment discovery
├── shared/
│   ├── security.ts              # security boundary: path containment, capability gating
│   ├── exec.ts                  # execution sandbox: argv-only, timeout, output cap
│   ├── evidence.ts              # EvidenceCollector, provenance, aggregateConfidence
│   ├── knowledge-base.ts        # knowledge store + evidence graph (atomic JSON)
│   ├── curated-datasets.ts      # curated reference data (real sources only)
│   └── types.ts                 # shared type contracts
├── skills/                      # Skills Library system (independent of engines)
│   ├── types.ts                 # SkillManifest, SkillSelection, type contracts
│   ├── frontmatter.ts           # YAML front-matter parser (no external dependency)
│   ├── loader.ts                # auto-discovery of skills/<name>/SKILL.md, validate + parse
│   └── registry.ts              # SkillRegistry: unique names, search, multi-select
├── prompts/index.ts             # 6 MCP prompt workflows
├── tools/
│   ├── helpers.ts               # defineTool / finish / addEvidence / artifact readers
│   └── platform.ts              # engine `platform`
└── engines/                     # 13 independent engines
```

### Tool execution flow

1. `ToolRegistry` pre-screens the tool descriptor through `evaluateIntent` (blocks forbidden
   capabilities).
2. `server.ts` checks `registry.screen(name)`; if blocked it returns `blocked: true` together with
   a **defensive alternative** instead of a generic refusal.
3. The handler runs with a `ToolContext` (logger, knowledge base, `EvidenceCollector`).
4. Results are wrapped in a **uniform** `ToolResult`: `ok`, `data`, `summary`, `evidence`,
   `assertions`, `warnings`, `blocked`, `durationMs`, `timestamp`.
5. After every call the knowledge base is `flush()`ed (atomic write).

---

## 5. Catalogue of 113 MCP tools

### `platform` (3)
`environment_report` · `health_check` · `dependency_diagnostics`

### `knowledge-and-evidence` (7)
`knowledge_search` · `knowledge_ingest` · `evidence_graph_query` · `source_provenance_check` ·
`research_report_generate` · `knowledge_update` · `research_checkpoint`

### `datasets` (3)
`curated_dataset_search` · `curated_dataset_ingest` · `curated_dataset_stats`

### `software-engineering` (17)
`engineering_toolchain_probe` · `repository_analyze` · `repository_search` · `symbol_search` ·
`dependency_analyze` · `documentation_search` · `architecture_analyze` · `source_generate` ·
`source_modify` · `source_review` · `source_refactor` · `build_project` · `run_tests` ·
`debug_project` · `regression_test` · `code_quality_report` · `project_memory`

### `malware-intelligence` (10)
`malware_sample_analyze` · `malware_family_compare` · `mirai_variant_analyze` ·
`malware_source_analyze` · `binary_similarity` · `malware_behavior_report` ·
`c2_protocol_analyze` · `ai_malware_indicator_analyze` · `honeypot_telemetry_analyze` ·
`botnet_lifecycle_stage_search`

### `zero-day-research` (16)
`zero_day_discovery_analyze` · `vulnerability_hypothesis_generate` · `vulnerability_hypothesis_rank` ·
`source_vulnerability_analyze` · `binary_vulnerability_analyze` · `firmware_vulnerability_analyze` ·
`static_analysis_run` · `fuzz_target_identify` · `fuzz_harness_generate` · `fuzzing_crash_analyze` ·
`crash_root_cause_analyze` · `vulnerability_verify` · `patch_root_cause_analyze` ·
`vulnerability_variant_hunt` · `zero_day_lifecycle_update` · `zero_day_research_report`

### `exploit-intelligence` (14)
`knowledge_source_registry` · `cve_search` · `cwe_search` · `advisory_search` ·
`exploit_reference_search` · `nuclei_template_search` · `yara_rule_search` · `sigma_rule_search` ·
`knowledge_source_sync` · `exploit_metadata_analyze` · `vulnerability_root_cause` ·
`patch_diff_analyze` · `safe_validation_generate` · `vulnerability_pipeline_report`

### `attack-methods` (6)
`attack_method_search` · `attack_method_classify` · `malware_attack_module_analyze` ·
`attack_behavior_analyze` · `attack_method_compare` · `attack_detection_recommend`

### `anti-ddos` (10)
`anti_ddos_research` · `defense_architecture_analyze` · `network_traffic_analyze` · `pcap_analyze` ·
`ddos_detection_design` · `detection_rule_generate` · `rate_limit_design` ·
`mitigation_strategy_compare` · `defense_test_plan` · `defense_performance_analyze`

### `firmware-intelligence` (8)
`firmware_analyze` · `firmware_extract` · `firmware_filesystem_analyze` · `elf_analyze` ·
`firmware_component_scan` · `emulation_plan` · `firmware_patch_diff` · `firmware_integrity_check`

### `network-forensics` (9)
`pcap_flow_analyze` · `pcap_dns_analyze` · `pcap_http_analyze` · `pcap_tls_metadata_analyze` ·
`c2_beacon_detect` · `ioc_extract` · `network_timeline_reconstruct` · `protocol_fingerprint` ·
`flow_summarize`

### `multi-agent` (7)
`agent_roles_list` · `orchestrator_plan` · `agent_brief_generate` · `agent_findings_merge` ·
`evidence_reconciliation` · `missing_evidence_identify` · `research_audit`

> Architecture §8/§11: **23 specialist roles** and **23 workstreams** are validated against
> dependencies; `agent_roles_list` lists roles, `orchestrator_plan` decomposes a task into
> parallelisable phases, and `agent_findings_merge` + `evidence_reconciliation` merge findings and
> reconcile evidence.

### `skills` (3)
`skill_list` · `skill_get` · `skill_select`

### MCP prompts (6)
`autonomous_task` · `malware_research_workflow` · `vulnerability_research_workflow` ·
`anti_ddos_defense_workflow` · `software_engineering_workflow` · `skill_workflow`

### MCP resources
`mirai://knowledge/stats` — knowledge base statistics as JSON.
`mirai://skills/index` — full Skills library listing (JSON: total, facets, per-skill metadata).

---

## 6. Skills library (engine `skills`)

The `skills` engine provides a **versioned technique library** that lets an agent discover,
inspect and combine multiple skills to solve complex tasks. Each skill is a `SKILL.md` file at
`skills/<name>/SKILL.md` following a standard schema:

- **YAML front matter**: `name`, `description`, `version`, `engines[]`, `tags[]`, `tools[]`, `license`
- **Body (Markdown)**: Purpose, Prerequisites, Inputs/Outputs, Procedure, Examples, Known
  limitations, Verification criteria, Provenance

### 36 skills available (version 1.0.0)

Each skill is a `skills/<name>/SKILL.md` with complete front matter and the standard body. Current
list:

`anti-ddos-defense` · `api-reverse-engineering` · `attack-source-engineering` ·
`automated-testing` · `binary-vulnerability-analysis` · `build-and-debug` · `code-review` ·
`evidence-based-research` · `evidence-validation-and-reconciliation` ·
`exploit-mechanism-research` · `exploit-source-analysis` · `exploit-source-code-analysis` ·
`firmware-analysis` · `firmware-zero-day-research` · `fuzzing-and-crash-triage` ·
`malware-configuration-extraction` · `malware-reverse-engineering` ·
`malware-source-code-analysis` · `malware-variant-comparison` ·
`memory-corruption-research` · `mirai-api-c2-protocol-analysis` ·
`mirai-botnet-lineage-analysis` · `mirai-c2-protocol-research` · `mirai-deep-source-analysis` ·
`mirai-variant-intelligence` · `patch-diff-and-variant-hunting` · `pcap-network-forensics` ·
`protocol-reverse-engineering` · `repository-analysis` · `research-tool-development` ·
`software-architecture` · `source-vulnerability-analysis` · `static-analysis-research` ·
`threat-intelligence-correlation` ·
`vulnerability-root-cause-analysis` · `zero-day-vulnerability-discovery`

### MCP tools

| Tool | Description |
|---|---|
| `skill_list` | List skills, filter by engine/tag, return facets |
| `skill_get` | Fetch the full skill content (front matter + body) |
| `skill_select` | Select and combine skills for a task → ranked recommendations + tool plan + workflow |

### MCP resource

`mirai://skills/index` — JSON: `{ root, total, facets: {engines, tags}, skills: [...] }`

### MCP prompt

`skill_workflow` — 8-step guide: list → select → get → execute tool plan → checkpoint → missing
evidence → reconciliation → final report.

### Quick usage

```json
// 1. Browse the library
{ "tool": "skill_list", "input": { "engine": "malware-intelligence", "limit": 10 } }

// 2. Pick skills for a task
{ "tool": "skill_select", "input": { "task": "analyze mirai botnet sample c2 protocol", "limit": 3 } }

// 3. Read skill details
{ "tool": "skill_get", "input": { "name": "mirai-api-c2-protocol-analysis" } }
```

---

## 7. Evidence model

Every conclusion carries **provenance** and **confidence**; hypotheses are never presented as
confirmed findings.

- `ConfidenceLevel`: `confirmed` → `observed` → `inferred` → `hypothesis` → `unknown`
- `EpistemicStatus`: `verified_fact` · `direct_observation` · `researcher_interpretation` ·
  `hypothesis` · `unverified_claim`
- `EvidenceRef` contains `claim`, `provenance` (source/url/publishedAt/retrievedAt/version/commit/license),
  `confidence`, `locator` (file/line/symbol/offset) and `data`.
- `Assertion` groups `supporting` + `contradicting` evidence.
- `aggregateConfidence()` computes confidence along the **weakest link**.
- `KnowledgeCategory` is **strictly separated**: `advisory`, `detection_template`,
  `fingerprint_template`, `exploit_poc`, `exploit_module`, `yara_rule`, `sigma_rule`,
  `network_detection_rule`, `remediation_guidance`, `patch_reference`, `research_paper`,
  `attack_method`, `defense_technology`, `dataset`, `firmware_component`, `malware_family`,
  `mirai_variant`, `c2_protocol_spec`, `malware_sample_ref`.
- `VerificationState`: `unverified` · `statically_reviewed` · `lab_validated_non_destructive` ·
  `disputed` — **a published PoC is not automatically treated as verified**.

---

## 8. Security boundary (§10)

Allowed: malware source and binary analysis, reverse engineering, root-cause analysis, safe PoC
analysis, non-destructive validation, isolated lab simulation, firmware analysis, PCAP analysis,
detection engineering, DDoS defence deployment, defensive automation, source development and
patching, regression testing, honeypot/sinkhole research.

**Not allowed** (hard-coded, cannot be enabled through configuration): deployable botnets,
automated recruitment/infection, worm propagation, malware persistence, unauthorised exploitation,
credential theft/brute force, botnet C2, operational DDoS code, distributed flooding,
reflection/amplification launchers, source spoofing, evasion code aimed at third-party products,
automated exploitation of public targets.

Enforcement:

- [security.ts](src/shared/security.ts) — `evaluateIntent()` matches forbidden capability patterns
  and returns a **defensive alternative**; `resolveWorkspacePath()` blocks path traversal outside
  the workspace; `requireLabAuthorization()` requires a token for active testing.
- [exec.ts](src/shared/exec.ts) — commands run as **argv (never through a shell)**, with hard
  timeout, output cap and `cwd` confined to the workspace.
- [registry.ts](src/core/registry.ts) — pre-screens every tool before its handler runs.

---

## 9. Testing

```
tests/
├── smoke.test.ts               # registry integrity + real execution of representative tools
├── skills.test.ts              # skill loader, registry, skill selection
├── multi-agent.test.ts         # roles, orchestrator plan, briefs, findings merge, reconciliation
├── mcp-protocol.test.ts        # real Client ↔ Server over InMemoryTransport
├── firmware-extract.test.ts    # cpio/tar parsing + firmware extraction regressions
├── binary-similarity.test.ts   # binary similarity engine
├── c2-protocol.test.ts         # C2 protocol analysis
├── crash-root-cause.test.ts    # crash triage
├── curated-datasets.test.ts    # curated dataset integrity
├── dependencies.test.ts        # dependency probing
├── source-vulnerability.test.ts # source vulnerability analysis
└── stdio-check.test.ts         # stdio handshake
```

`tests/mcp-protocol.test.ts` also verifies the **policy gate**: with
`MIRAI_ALLOW_PUBLIC_FETCH=false`, `cve_search` returns `blocked: true` instead of touching the
network.

```bash
npm run verify
```

---

## 10. Adding a new engine

```ts
// src/engines/my-engine/index.ts
import type { EngineModule } from '../../core/tool.js';
import { defineTool, finish } from '../../tools/helpers.js';
import { z } from 'zod';

const ENGINE = 'my-engine';

export const myEngine: EngineModule = {
  name: ENGINE,
  title: 'My Engine',
  description: 'Engine description.',
  tools: [
    defineTool({
      name: 'my_tool',
      title: 'My tool',
      engine: ENGINE,
      description: 'Tool description.',
      capabilities: ['read_repo'],
      risk: 'safe',
      inputSchema: { path: z.string() },
      handler: async (input, ctx) => {
        const started = Date.now();
        const { path } = input as { path: string };
        return finish({
          engine: ENGINE, tool: 'my_tool', startedAt: started, ctx,
          data: { path },
          summary: `Processed ${path}.`,
        });
      },
    }),
  ],
};
```

Mandatory constraints: relative imports must end with `.js`; tool names must match
`/^[a-z][a-z0-9_]{2,63}$/` and be globally unique; `descriptor.engine` must equal
`EngineModule.name`. Then add the engine to the `ENGINES` array in [index.ts](src/index.ts).

---

## 11. Known limitations

- HTTP transport is not implemented (stdio only).
- Deep analysis (Ghidra headless, QEMU emulation, Zeek/Suricata) depends on external tools in
  `PATH`; when missing, the platform falls back to pure-JS analysis (PCAP/ELF/firmware carving) and
  states so in the result. Per-dependency status is exposed by `dependency_diagnostics`; a missing
  dependency yields a structured `TOOL_MISSING` error and must not be treated as executed.
- `emulation_plan` only **produces a plan**; it never executes untrusted firmware emulation.
- `defense_test_plan` only produces a plan; active traffic testing requires `MIRAI_LAB_TOKEN`.
- Curated data in `curated-datasets.ts` contains only verified public events; uncertain items were
  dropped rather than inferred.

---

## License

MIT — see [LICENSE](LICENSE).

**Core philosophy: Understand deeply. Research rigorously. Engineer intelligently. Verify everything. Defend effectively.**