security-ownership-map

Analyze git repositories to build a security ownership topology (people-to-file), compute bus factor and sensitive-code ownership, and export CSV/JSON for graph databases and visualization. Trigger only when the user explicitly wants a security-oriented ownership or bus-factor analysis grounded in git history (for example: orphaned sensitive code, security maintainers, CODEOWNERS reality checks for risk, sensitive hotspots, or ownership clusters). Do not trigger for general maintainer lists or non-security ownership questions.

installs

stars

7,309

karma

SkillRank score ↗

7.2/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-05-26

security-ownership-map analyzes git history to build people-file graphs, compute bus factor and sensitive-code clusters, and export for neo4j or gephi. flags orphaned sensitive code, ownership drift vs codeowners, and hidden concentration risk in auth/crypto.

structure

8.0

trigger phrases

9.0

procedure

8.0

edge cases

6.0

documentation

7.0

strengths

view original SKILL.md from smitheryclick to expand

---
name: "security-ownership-map"
description: "Analyze git repositories to build a security ownership topology (people-to-file), compute bus factor and sensitive-code ownership, and export CSV/JSON for graph databases and visualization. Trigger only when the user explicitly wants a security-oriented ownership or bus-factor analysis grounded in git history (for example: orphaned sensitive code, security maintainers, CODEOWNERS reality checks for risk, sensitive hotspots, or ownership clusters). Do not trigger for general maintainer lists or non-security ownership questions."
---

# Security Ownership Map

## Overview

Build a bipartite graph of people and files from git history, then compute ownership risk and export graph artifacts for Neo4j/Gephi. Also build a file co-change graph (Jaccard similarity on shared commits) to cluster files by how they move together while ignoring large, noisy commits.

## Requirements

- Python 3
- `networkx` (required; community detection is enabled by default)

Install with:

```bash
pip install networkx
```

## Workflow

1. Scope the repo and time window (optional `--since/--until`).
2. Decide sensitivity rules (use defaults or provide a CSV config).
3. Build the ownership map with `scripts/run_ownership_map.py` (co-change graph is on by default; use `--cochange-max-files` to ignore supernode commits).
4. Communities are computed by default; graphml output is optional (`--graphml`).
5. Query the outputs with `scripts/query_ownership.py` for bounded JSON slices.
6. Persist and visualize (see `references/neo4j-import.md`).

By default, the co-change graph ignores common “glue” files (lockfiles, `.github/*`, editor config) so clusters reflect actual code movement instead of shared infra edits. Override with `--cochange-exclude` or `--no-default-cochange-excludes`. Dependabot commits are excluded by default; override with `--no-default-author-excludes` or add patterns via `--author-exclude-regex`.

If you want to exclude Linux build glue like `Kbuild` from co-change clustering, pass:

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

## Quick start

Run from the repo root:

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

Defaults: author identity, author date, and merge commits excluded. Use `--identity committer`, `--date-field committer`, or `--include-merges` if needed.

Example (override co-change excludes):

```bash
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
```

Communities are computed by default. To disable:

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

## Sensitivity rules

By default, the script flags common auth/crypto/secret paths. Override by providing a CSV file:

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

Use it with `--sensitive-config path/to/sensitive.csv`.

## Output artifacts

`ownership-map-out/` contains:

- `people.csv` (nodes: people)
- `files.csv` (nodes: files)
- `edges.csv` (edges: touches)
- `cochange_edges.csv` (file-to-file co-change edges with Jaccard weight; omitted with `--no-cochange`)
- `summary.json` (security ownership findings)
- `commits.jsonl` (optional, if `--emit-commits`)
- `communities.json` (computed by default from co-change edges when available; includes `maintainers` per community; disable with `--no-communities`)
- `cochange.graph.json` (NetworkX node-link JSON with `community_id` + `community_maintainers`; falls back to `ownership.graph.json` if no co-change edges)
- `ownership.graphml` / `cochange.graphml` (optional, if `--graphml`)

`people.csv` includes timezone detection based on author commit offsets: `primary_tz_offset`, `primary_tz_minutes`, and `timezone_offsets`.

## LLM query helper

Use `scripts/query_ownership.py` to return small, JSON-bounded slices without loading the full graph into context.

Examples:

```bash
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
```

Use `--community-top-owners 5` (default) to control how many maintainers are stored per community.

## Basic security queries

Run these to answer common security ownership questions with bounded output:

```bash
# Orphaned sensitive code (stale + low bus factor)
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section orphaned_sensitive_code

# Hidden owners for sensitive tags
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section hidden_owners

# Sensitive hotspots with low bus factor
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section bus_factor_hotspots

# Auth/crypto files with bus factor <= 1
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

# Who is touching sensitive code the most
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out people --sort sensitive_touches --limit 10

# Co-change neighbors (cluster hints for ownership drift)
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

# Community maintainers (for a cluster)
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out community --id 3

# Monthly maintainers for the community containing a file
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

# Quarterly buckets instead of monthly
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
```

Notes:
- Touches default to one authored commit (not per-file). Use `--touch-mode file` to count per-file touches.
- Use `--window-days 90` or `--weight recency --half-life-days 180` to smooth churn.
- Filter bots with `--ignore-author-regex '(bot|dependabot)'`.
- Use `--min-share 0.1` to show stable maintainers only.
- Use `--bucket quarter` for calendar quarter groupings.
- Use `--identity committer` or `--date-field committer` to switch from author attribution.
- Use `--include-merges` to include merge commits (excluded by default).

### Summary format (default)

Use this structure, add fields if needed:

```json
{
  "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"
    }
  ]
}
```

## Graph persistence

Use `references/neo4j-import.md` when you need to load the CSVs into Neo4j. It includes constraints, import Cypher, and visualization tips.

## Notes

- `bus_factor_hotspots` in `summary.json` lists sensitive files with low bus factor; `orphaned_sensitive_code` is the stale subset.
- If `git log` is too large, narrow with `--since` or `--until`.
- Compare `summary.json` against CODEOWNERS to highlight ownership drift.

don't have the plugin yet? install it then click "run inline in claude" again.

separated frontmatter and structured skill into implexa's 6 required sections, made all decision logic explicit (committer vs author, merge handling, co-change noise, community detection toggles, bot filtering, time windowing), detailed inputs with setup guidance, clarified each procedure step with explicit inputs and outputs, documented edge cases (supernodes, noisy co-change, git log size, codeowners drift), and added outcome signals for both local analysis and neo4j persistence.

Security Ownership Map

Item: security-ownership-map
Rating: 7.2
Author: Implexa

intent

map people to files and files to files via git history to surface security ownership risk (orphaned sensitive code, bus factor hotspots, hidden owners). use this when you need to answer: who owns crypto? what auth code has only one maintainer? which sensitive files are stale? do not use for general maintainer lists or non-security ownership questions.

inputs

git repository

local path required (must be a valid git repo with commit history)
time window optional (--since/--until flags; defaults to full history)

python environment

python 3.8+ required
networkx library required for community detection (install: pip install networkx)

sensitivity configuration (optional)

csv file defining what counts as "sensitive" (auth, crypto, secrets patterns, etc.)
format: pattern,tag,weight (one per line; globs supported)
if not provided, defaults to common paths like **/auth/**, **/crypto/**, **/*.pem

git author filters (optional)

regex patterns to exclude authors (bots, ci systems, dependabot, etc.)
defaults: dependabot and common ci patterns excluded
override with --no-default-author-excludes or --author-exclude-regex

co-change exclusions (optional)

glob patterns for files to ignore in co-change clustering (lockfiles, editor config, infra glue)
defaults: .github/*, lockfiles, editor configs
override with --cochange-exclude or --no-default-cochange-excludes

external connections

none required (git local only) for analysis
neo4j optional for persistence (see references/neo4j-import.md if you want to load outputs there)

procedure

initialize the run with repo path and output directory:
- input: --repo /path/to/repo --out ownership-map-out
- output: confirms repo is valid and output dir is writable
scope time window (optional) to reduce noise and runtime:
- input: --since "12 months ago" or --until "2024-12-31"
- output: commit range selected; filters applied before graph build
configure sensitivity rules (optional) if defaults don't match your codebase:
- input: csv file with pattern,tag,weight rows
- output: sensitivity config loaded into script context
set author/commit filters (optional) to exclude noise:
- input: --author-exclude-regex pattern, --identity committer (vs author), --include-merges flag
- output: commit set filtered; attribution locked to chosen field
configure co-change clustering (optional) to avoid supernodes and glue files:
- input: --cochange-exclude globs, --cochange-max-files threshold, or --no-cochange flag
- output: co-change edge list pruned; noisy files removed from clustering
run ownership map script:
- input: python skills/skills/security-ownership-map/scripts/run_ownership_map.py [flags from steps 1-5]
- output: CSVs written to ownership-map-out/ (people.csv, files.csv, edges.csv, cochange_edges.csv)
community detection runs by default (unless disabled with --no-communities):
- input: co-change graph (if present)
- output: communities.json with community_id, community_maintainers, and cochange.graph.json with node-level community assignment
optional: emit commit details for audit trails:
- input: --emit-commits flag
- output: commits.jsonl written (one json object per commit)
optional: export graphml for visualization tools (neo4j, gephi):
- input: --graphml flag
- output: ownership.graphml and/or cochange.graphml written to output dir
query the outputs using the helper script for bounded json slices (do not load full graph into context):
- input: python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out [query type] [filters]
- output: json or csv snippet matching the query (people, files, communities, summary sections, cochange neighbors, etc.)
persist to graph db (optional) if you need interactive queries or visualization:
- input: ownership-map-out CSVs + neo4j instance + import cypher from references/neo4j-import.md
- output: nodes and edges loaded into neo4j; ready for cypher queries

decision points

if you want to analyze committer instead of author:

use --identity committer and --date-field committer (defaults are author-based)

if the repo has many merge commits and they are noise:

use default (merges excluded); if you need merges, pass --include-merges

if co-change graph is too noisy (supernodes hiding real clusters):

pass --cochange-max-files N to ignore commits touching more than N files
pass --cochange-exclude to skip known glue files (e.g., lockfiles, Kbuild, .github/*)
pass --no-default-cochange-excludes to use your exclusions only

if you want to disable community detection:

pass --no-communities (useful for very large repos or if you don't need clustering)

if default sensitivity patterns don't match your codebase:

provide a csv config file with custom patterns/tags/weights via --sensitive-config

if bot/ci commits are polluting the ownership map:

pass --author-exclude-regex to filter (e.g., (dependabot|renovate|renovate-bot))
pass --no-default-author-excludes to use your regex only

if git log is too large or slow:

narrow the time window with --since or --until
consider analyzing a subdirectory instead of the full repo

if you need to compare against CODEOWNERS:

export summary.json and manually diff against your CODEOWNERS file to surface ownership drift

output contract

csv files (in ownership-map-out/):

people.csv: columns include email, commit_count, sensitive_touches, primary_tz_offset, timezone_offsets, first_commit, last_commit
files.csv: columns include path, tag (auth/crypto/secrets/etc.), bus_factor, sensitive_weight, last_touch, num_authors
edges.csv: columns include person, file, touches (number of commits)
cochange_edges.csv (optional): columns include file_a, file_b, jaccard_similarity, shared_commits (file-to-file edges)

json files (in ownership-map-out/):

summary.json: top-level keys: orphaned_sensitive_code, bus_factor_hotspots, hidden_owners (each with matched files/people and metadata)
communities.json: array of community objects, each with id, members (list of people), maintainers (top owners), stability_score
cochange.graph.json or ownership.graph.json: networkx node-link format; nodes include community_id and community_maintainers; edges include weight

optional files:

commits.jsonl (if --emit-commits): one json object per commit with hash, author, date, files_touched, message
ownership.graphml / cochange.graphml (if --graphml): graphml format for gephi or neo4j desktop

outcome signal

script runs without error: repo is valid, output dir created, git history parsed
csv files populated: people.csv and files.csv have rows; edges.csv has touches; if cochange is enabled, cochange_edges.csv is present
summary.json contains security findings: at least one of orphaned_sensitive_code, bus_factor_hotspots, or hidden_owners has matches (non-empty arrays)
communities.json is populated (if --no-communities not passed): community_id values in cochange.graph.json match community objects in communities.json
query_ownership.py returns bounded results: running queries like --data-dir ownership-map-out files --tag auth --bus-factor-max 1 returns matching rows within reasonable json size
neo4j import succeeds (if you run it): cypher commands from neo4j-import.md load CSVs into neo4j without constraint violations

security-ownership-map

related skills

Security Ownership Map

intent

inputs

procedure

decision points

output contract

outcome signal