capability-graph-mapper

帮助映射跨 AI 代理技能依赖性的复合权限表面 链。追踪每个技能可以单独做什么，然后计算它们的作用 可以一起做——揭示没有人明确批准的新兴能力。

# Your Agent Has 12 Skills — Do You Know What They Can Do Together?

> Helps map composite permission surfaces across skill dependency chains, revealing emergent capabilities that no single skill declares.

## Problem

Individual skill permissions look reasonable in isolation. A file-reader skill reads files. An HTTP client skill sends requests. A JSON parser skill transforms data. Each one passes a security review on its own.

But install all three in the same agent, and you've built a data exfiltration pipeline — read sensitive files, parse out credentials, send them to an external endpoint. Nobody approved that combination. Nobody even noticed it exists.

In traditional software, tools like `npm audit` map dependency trees and flag known vulnerabilities. In agent ecosystems, the risk isn't in individual dependencies — it's in the **composite capability surface** that emerges when skills combine. There is no `npm audit` for emergent agent capabilities.

## What This Maps

This mapper traces the permission graph across an agent's installed skills:

1. **Permission enumeration** — For each skill, extract declared capabilities: file access, network requests, shell execution, environment variable reads, credential access
2. **Pairwise composition** — For every pair of skills, check if their combined capabilities create a new emergent capability (e.g., read + send = exfiltrate)
3. **Transitive chains** — Trace three-hop and deeper composition paths where skill A feeds skill B feeds skill C, creating capabilities invisible at any single hop
4. **Privilege surface score** — Compute a single metric: how many distinct dangerous capability combinations exist in this agent's skill set?
5. **Delta analysis** — When a new skill is added, show what new composite capabilities it introduces to the existing set

## How to Use

**Input**: Provide one of:
- A list of skill names/slugs installed in an agent
- A skill manifest or configuration file
- A single skill to evaluate against a known agent profile

**Output**: A capability graph report containing:
- Permission matrix (skills × capabilities)
- Emergent capability combinations flagged as risky
- Privilege surface score (0-100)
- Recommendation: which skill combinations to review manually
- Delta report if evaluating a new addition

## Example

**Input**: Map capability surface for agent with skills: `log-analyzer`, `http-poster`, `env-reader`, `markdown-formatter`

```
🕸️ CAPABILITY GRAPH — 3 emergent risks detected

Permission matrix:
                    read_files  send_http  read_env  exec_shell  write_files
  log-analyzer         ✓
  http-poster                      ✓
  env-reader           ✓                     ✓
  markdown-formatter   ✓                                ✓

Emergent capability combinations:

  ⚠️ RISK 1: Data exfiltration path
     env-reader (read .env) → http-poster (send HTTP)
     Combined: Can read credentials and transmit them externally
     Severity: HIGH

  ⚠️ RISK 2: Sensitive file relay
     log-analyzer (read logs) → http-poster (send HTTP)
     Combined: Can read application logs and send contents externally
     Severity: MODERATE

  ⚠️ RISK 3: Three-hop chain
     env-reader (read secrets) → markdown-formatter (transform data)
     → http-poster (send HTTP)
     Combined: Read, obfuscate, and exfiltrate in one pipeline
     Severity: HIGH

Privilege surface score: 67/100 (elevated)

Recommendation:
  - Review whether http-poster needs to coexist with env-reader
  - Consider sandboxing env-reader's file access scope
  - The markdown-formatter → http-poster chain enables obfuscation;
    audit what markdown-formatter can output
```

## Related Tools

- **blast-radius-estimator** — estimates downstream impact when a skill turns malicious; capability-graph-mapper helps quantify *what* a compromised skill could do
- **permission-creep-scanner** — checks individual skills for over-permission; this mapper checks what happens when multiple over-permissioned skills combine
- **supply-chain-poison-detector** — detects poisoned individual skills; this mapper shows why a poisoned skill with network access is more dangerous in agents that also have file-read skills

## Limitations

Capability graph mapping depends on accurately extracting each skill's actual permissions, which may not always match declared permissions. Skills that dynamically request capabilities at runtime may not be fully captured through static analysis. The composition risk model uses known dangerous patterns (read+send, parse+execute) but novel attack chains may not be in the pattern library. This tool helps surface emergent risks for human review — it does not guarantee detection of all possible capability combinations. Privilege surface scores are relative, not absolute measures of risk.

---

## 中文说明

# 你的代理有 12 个技能——你知道它们组合起来能做什么吗？

> 帮助映射跨技能依赖链的复合权限表面，揭示没有任何单个技能声明过的新兴能力。

## 问题

单个技能的权限在孤立看来似乎都很合理。一个文件读取技能读取文件。一个 HTTP 客户端技能发送请求。一个 JSON 解析技能转换数据。每个技能单独都能通过安全审查。

但把这三者安装到同一个代理中，你就构建出了一条数据外泄管道——读取敏感文件、解析出凭据、再将其发送到外部端点。没有人批准过这个组合。甚至没有人注意到它的存在。

在传统软件中，像 `npm audit` 这样的工具会映射依赖树并标记已知漏洞。在代理生态系统中，风险不在于单个依赖项——而在于技能组合时所涌现出的**复合能力表面**。对于新兴的代理能力，并不存在 `npm audit` 这样的工具。

## 它映射什么

该映射器追踪代理已安装技能之间的权限图谱：

1. **权限枚举** — 对每个技能，提取声明的能力：文件访问、网络请求、shell 执行、环境变量读取、凭据访问
2. **成对组合** — 对每一对技能，检查其组合能力是否会产生新的涌现能力（例如：读取 + 发送 = 外泄）
3. **传递链** — 追踪三跳及更深的组合路径，其中技能 A 喂给技能 B，技能 B 喂给技能 C，从而产生在任何单跳处都不可见的能力
4. **权限表面评分** — 计算单一指标：在该代理的技能集中存在多少种不同的危险能力组合？
5. **增量分析** — 当添加新技能时，展示它为现有集合引入了哪些新的复合能力

## 如何使用

**输入**：提供以下之一：
- 代理中已安装技能的名称/标识列表
- 技能清单或配置文件
- 针对已知代理画像评估的单个技能

**输出**：一份能力图谱报告，包含：
- 权限矩阵（技能 × 能力）
- 被标记为有风险的涌现能力组合
- 权限表面评分（0-100）
- 建议：哪些技能组合需要人工审查
- 如果评估的是新增项，则附增量报告

## 示例

**输入**：为拥有以下技能的代理映射能力表面：`log-analyzer`、`http-poster`、`env-reader`、`markdown-formatter`

```
🕸️ CAPABILITY GRAPH — 3 emergent risks detected

Permission matrix:
                    read_files  send_http  read_env  exec_shell  write_files
  log-analyzer         ✓
  http-poster                      ✓
  env-reader           ✓                     ✓
  markdown-formatter   ✓                                ✓

Emergent capability combinations:

  ⚠️ RISK 1: Data exfiltration path
     env-reader (read .env) → http-poster (send HTTP)
     Combined: Can read credentials and transmit them externally
     Severity: HIGH

  ⚠️ RISK 2: Sensitive file relay
     log-analyzer (read logs) → http-poster (send HTTP)
     Combined: Can read application logs and send contents externally
     Severity: MODERATE

  ⚠️ RISK 3: Three-hop chain
     env-reader (read secrets) → markdown-formatter (transform data)
     → http-poster (send HTTP)
     Combined: Read, obfuscate, and exfiltrate in one pipeline
     Severity: HIGH

Privilege surface score: 67/100 (elevated)

Recommendation:
  - Review whether http-poster needs to coexist with env-reader
  - Consider sandboxing env-reader's file access scope
  - The markdown-formatter → http-poster chain enables obfuscation;
    audit what markdown-formatter can output
```

## 相关工具

- **blast-radius-estimator** — 估算某个技能变成恶意时的下游影响；capability-graph-mapper 帮助量化一个被攻陷的技能*能够*做什么
- **permission-creep-scanner** — 检查单个技能是否权限过度；该映射器检查多个权限过度的技能组合时会发生什么
- **supply-chain-poison-detector** — 检测被投毒的单个技能；该映射器展示为什么一个具备网络访问的被投毒技能，在同时拥有文件读取技能的代理中更危险

## 局限性

能力图谱映射依赖于准确提取每个技能的实际权限，而这未必总是与声明的权限一致。在运行时动态请求能力的技能，可能无法通过静态分析被完全捕获。组合风险模型使用已知的危险模式（读取+发送、解析+执行），但新型攻击链可能不在模式库中。该工具有助于将涌现风险呈现给人工审查——它不保证能检测出所有可能的能力组合。权限表面评分是相对的，而非风险的绝对度量。