安全所有权映射工具Skill security-ownership-map

---

名称: 安全所有权映射 描述: ‘分析Git仓库以构建安全所有权拓扑（人员到文件），计算总线因子和敏感代码所有权，并导出CSV/JSON用于图数据库和可视化。仅在用户明确需要基于Git历史的安全导向所有权或总线因子分析时触发（例如：孤儿敏感代码、安全维护者、CODEOWNERS现实检查风险、敏感热点或所有权集群）。不要为一般维护者列表或非安全所有权问题触发。’ 元数据: 作者: github.com/openai/skills 版本: ‘1.0.0’

安全所有权映射

概述

从Git历史构建人员和文件的二分图，然后计算所有权风险并导出图数据用于Neo4j/Gephi。同时构建文件共同变更图（基于共享提交的Jaccard相似度），通过文件如何一起变动来聚类文件，同时忽略大型嘈杂提交。

要求

• Python 3
• networkx（必需；社区检测默认启用）

安装方法：

pip install networkx

工作流程

1. 定义仓库范围和时间窗口（可选 --since/--until）。
2. 决定敏感规则（使用默认或提供CSV配置）。
3. 使用 scripts/run_ownership_map.py 构建所有权映射（共同变更图默认开启；使用 --cochange-max-files 忽略超节点提交）。
4. 社区默认计算；graphml输出可选（--graphml）。
5. 使用 scripts/query_ownership.py 查询输出以获取有界JSON切片。
6. 持久化和可视化（参见 references/neo4j-import.md）。

默认情况下，共同变更图忽略常见的“粘合”文件（锁文件、.github/*、编辑器配置），以便聚类反映实际代码变动而非共享基础设施编辑。使用 --cochange-exclude 或 --no-default-cochange-excludes 覆盖。Dependabot提交默认排除；使用 --no-default-author-excludes 或通过 --author-exclude-regex 添加模式覆盖。

如果要从共同变更聚类中排除Linux构建粘合文件如 Kbuild，传递：

python skills/skills/security-ownership-map/scripts/run_ownership_map.py \
  --repo /path/to/linux \
  --out ownership-map-out \
  --cochange-exclude "**/Kbuild"

快速开始

从仓库根目录运行：

python skills/skills/security-ownership-map/scripts/run_ownership_map.py \
  --repo . \
  --out ownership-map-out \
  --since "12 months ago" \
  --emit-commits

默认：作者身份、作者日期和合并提交排除。如果需要，使用 --identity committer、--date-field committer 或 --include-merges。

示例（覆盖共同变更排除）：

python skills/skills/security-ownership-map/scripts/run_ownership_map.py \
  --repo . \
  --out ownership-map-out \
  --cochange-exclude "**/Cargo.lock" \
  --cochange-exclude "**/.github/**" \
  --no-default-cochange-excludes

社区默认计算。禁用：

python skills/skills/security-ownership-map/scripts/run_ownership_map.py \
  --repo . \
  --out ownership-map-out \
  --no-communities

敏感规则

默认情况下，脚本标记常见的auth/crypto/secret路径。通过提供CSV文件覆盖：

# pattern,tag,weight
**/auth/**,auth,1.0
**/crypto/**,crypto,1.0
**/*.pem,secrets,1.0

使用 --sensitive-config path/to/sensitive.csv。

输出产物

ownership-map-out/ 包含：

• people.csv（节点：人员）
• files.csv（节点：文件）
• edges.csv（边：接触）
• cochange_edges.csv（文件到文件共同变更边，带Jaccard权重；使用 --no-cochange 省略）
• summary.json（安全所有权发现）
• commits.jsonl（可选，如果 --emit-commits）
• communities.json（默认从共同变更边计算；包括每个社区的 maintainers；使用 --no-communities 禁用）
• cochange.graph.json（NetworkX节点链接JSON，带 community_id + community_maintainers；如果没有共同变更边，回退到 ownership.graph.json）
• ownership.graphml / cochange.graphml（可选，如果 --graphml）

people.csv 包括基于作者提交偏移的时区检测：primary_tz_offset、primary_tz_minutes 和 timezone_offsets。

LLM查询助手

使用 scripts/query_ownership.py 返回小的、JSON有界切片，无需将完整图加载到上下文中。

示例：

python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out people --limit 10
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out files --tag auth --bus-factor-max 1
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out person --person alice@corp --limit 10
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out file --file crypto/tls
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out cochange --file crypto/tls --limit 10
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section orphaned_sensitive_code
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out community --id 3

使用 --community-top-owners 5（默认）控制每个社区存储多少维护者。

基本安全查询

运行这些以回答常见安全所有权问题，输出有界：

# 孤儿敏感代码（陈旧 + 低总线因子）
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section orphaned_sensitive_code

# 敏感标签的隐藏所有者
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section hidden_owners

# 低总线因子的敏感热点
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section bus_factor_hotspots

# 总线因子 <= 1 的Auth/crypto文件
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out files --tag auth --bus-factor-max 1
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out files --tag crypto --bus-factor-max 1

# 谁最常接触敏感代码
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out people --sort sensitive_touches --limit 10

# 共同变更邻居（所有权漂移的集群提示）
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out cochange --file path/to/file --min-jaccard 0.05 --limit 20

# 社区维护者（针对集群）
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out community --id 3

# 包含文件的社区的月度维护者
python skills/skills/security-ownership-map/scripts/community_maintainers.py \
  --data-dir ownership-map-out \
  --file network/card.c \
  --since 2025-01-01 \
  --top 5

# 季度分组而非月度
python skills/skills/security-ownership-map/scripts/community_maintainers.py \
  --data-dir ownership-map-out \
  --file network/card.c \
  --since 2025-01-01 \
  --bucket quarter \
  --top 5

注意：

• 接触默认计算一次作者提交（非每文件）。使用 --touch-mode file 计算每文件接触。
• 使用 --window-days 90 或 --weight recency --half-life-days 180 平滑变动。
• 使用 --ignore-author-regex '(bot|dependabot)' 过滤机器人。
• 使用 --min-share 0.1 仅显示稳定维护者。
• 使用 --bucket quarter 进行日历季度分组。
• 使用 --identity committer 或 --date-field committer 切换作者归属。
• 使用 --include-merges 包括合并提交（默认排除）。

摘要格式（默认）

使用此结构，如果需要添加字段：

{
  "orphaned_sensitive_code": [
    {
      "path": "crypto/tls/handshake.rs",
      "last_security_touch": "2023-03-12T18:10:04+00:00",
      "bus_factor": 1
    }
  ],
  "hidden_owners": [
    {
      "person": "alice@corp",
      "controls": "63% of auth code"
    }
  ]
}

图持久化

需要将CSV加载到Neo4j时使用 references/neo4j-import.md。它包括约束、导入Cypher和可视化提示。

注意

• summary.json 中的 bus_factor_hotspots 列出低总线因子的敏感文件；orphaned_sensitive_code 是陈旧的子集。
• 如果 git log 太大，使用 --since 或 --until 缩小范围。
• 将 summary.json 与CODEOWNERS比较以突出所有权漂移。