convez.ai
MCP Server
cognis-digital

agentmap

cognis-digital/agentmap

Ver no GitHub
InicialPluginScore · de 0 a 100

Discover and map agent-to-agent / MCP communications and flag shadow AI

Instalação

$npx convez-ai cognis-digital/agentmap

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
0
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 4 meses
Versão
—
Issues abertas
1
Contribuidores
2

README

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

agentmap — discover & map agent-to-agent / MCP communications, flag shadow AI

Part of the Cognis Neural Suite by Cognis Digital Cognis Open Collaboration License (COCL) v1.0 · domain: ai-security

PyPI CI License: COCL 1.0 Suite

Map the agent-to-agent and agent-to-MCP communication graph and surface "shadow AI".

AI Security & Governance — securing LLMs, agents, and the MCP supply chain.

Usage — step by step

  1. Install the mapper:
    pip install cognis-agentmap
    
  2. Map a project — point map at a directory (or single file) holding mcp.json, agent configs, .env, or observations.json. It discovers config sources and builds the communication graph:
    agentmap map demos/01-basic
    
  3. Filter findings by severity while you triage. --min-severity controls what is reported:
    agentmap map demos/01-basic --min-severity low
    
  4. Read the output in the format you need. --format accepts table (default), json, mermaid, or sarif; --out writes to a file:
    agentmap map demos/01-basic --format mermaid --out graph.mmd   # paste into any Mermaid renderer
    agentmap map demos/01-basic --format json --out graph.json
    
  5. Automate in CI — --fail-on exits non-zero when a finding at or above the threshold appears (default high):
    - run: pip install cognis-agentmap
    - run: agentmap map . --format sarif --out agentmap.sarif --fail-on high
    

Why

LLM agents quietly accumulate MCP servers, peer agents, and tools. Most of those links are configured ad-hoc: some are authenticated, many are not, and almost none are logged. agentmap reads the config you already have on disk — mcp.json, agent config files, your .env, and (optionally) an observations capture — normalizes them into one typed graph of agents ↔ MCP servers ↔ tools, then flags every link that is unauthenticated, unmonitored, or undeclared (shadow AI). Stdlib only, scriptable, CI-friendly, self-hostable.

Install

pip install cognis-agentmap
# or, from this repo:
pip install -e ".[dev]"

Quick start

agentmap --version
agentmap map demos/01-basic                      # human-readable map + findings
agentmap map demos/01-basic --format json        # machine-readable graph
agentmap map demos/01-basic --format mermaid      # paste into any Mermaid renderer
agentmap map demos/01-basic --format sarif --out r.sarif
agentmap map demos/01-basic --fail-on high        # CI gate on high+ findings
python -m agentmap.mcp_server                      # expose as an MCP server

What it reads

SourcePatternContributes
MCP client configmcp.json, *.mcp.json, *-mcp.json, any JSON with mcpServersMCP-server + tool nodes, host→server edges
Agent configagents.json, *.agent.json, JSON with agentsagent nodes, agent→server (uses) + agent→agent (a2a) edges
Env file.env, *.envcredential presence; a server whose auth depends on a missing env var is treated as unauthenticated
Observationsconnections.json / observations.jsonempirically observed edges; any endpoint not in the declared inventory = shadow AI

What it flags

  • link.unauthenticated — a link no credential protects.
  • link.auth_env_missing — auth references an env var that is absent → effectively unauthenticated.
  • link.unmonitored — no logging/audit on the link; misuse would be invisible.
  • shadow.undeclared_endpoint (critical) — observed traffic to an agent/server in no config inventory.
  • shadow.undeclared_link — an observed channel between known nodes that nothing declared.
  • graph.orphan_server — a declared MCP server nothing references.

Output formats

  • Table (default) — human-readable terminal summary of nodes, links, and findings.
  • JSON — full graph (nodes, edges, findings, summary, risk_score).
  • Mermaid — a flowchart with risky links styled red.
  • SARIF — drops into GitHub code-scanning / IDE problem panes.

Built-in demo scenario

demos/01-basic/ — a mixed estate (3 MCP servers, 2 agents, an .env, and a telemetry capture). It maps cleanly except for one unauthenticated MCP server (weather) and a shadow agent (rogue-scraper) seen in observations but declared nowhere.

How it fits the Cognis Neural Suite

agentmap is one tool in the Cognis Neural Suite. Every tool ships an MCP server, so Cognis.Studio agents can call them as scoped capabilities.

Sibling tools in ai-security: mcpharden, agentlog, guardpost, aegis, promptmirror

Contributing

PRs, new detections, and demo scenarios are welcome under the collaboration-pull model. See CONTRIBUTING.md and SECURITY.md.

Interoperability

agentmap composes with the 300+ tool Cognis suite — JSON in/out and a shared OpenAI-compatible /v1 backbone. See INTEROP.md for the suite map, composition patterns, and reference stacks.

Integrations

Forward agentmap's findings to STIX/MISP/Sigma/Splunk/Elastic/Slack/webhooks via cognis-connect. See INTEGRATIONS.md.

License

Source-available under the Cognis Open Collaboration License (COCL) v1.0 — free for personal, internal-evaluation, research, and educational use; commercial / production use requires a license (licensing@cognis.digital). See LICENSE.

Responsible use

This is dual-use security software. Use it only against systems, data, and identities you own or are explicitly authorized in writing to test, and in compliance with applicable law.

About

Cognis Digital — Wyoming, USA · Making Tomorrow Better Today: Advanced Cybersecurity, AI Innovation, and Blockchain Expertise.

Ver o original no GitHub

Bom para

Relacionados