Contributing to SecID

What You're Contributing To

A registry of 709+ security knowledge sources across 10 types

Every entry is one JSON file per namespace. Adding a new organization = adding a file. Adding another source from an existing organization = adding a match_node to their file.

Registry File Format

One JSON file per namespace, containing all sources from that organization

{
  "schema_version": "1.0",
  "namespace": "mitre.org",
  "type": "advisory",
  "status": "published",
  "official_name": "MITRE Corporation",
  "urls": [
    {"type": "website", "url": "https://www.mitre.org/"}
  ],
  "match_nodes": [
    {
      "patterns": ["(?i)^cve$"],
      "description": "Common Vulnerabilities and Exposures",
      "weight": 100,
      "data": { ... },
      "children": [ ... ]
    }
  ]
}

Namespace-to-Filesystem Algorithm

Domain name → reverse-DNS directory path

mitre.org  →  registry/advisory/org/mitre.json
nist.gov   →  registry/control/gov/nist.json
redhat.com →  registry/advisory/com/redhat.json

github.com/advisories  →  registry/advisory/com/github/advisories.json

Steps:

1. Split domain on . → mitre, org
2. Reverse → org/mitre
3. Append path portion (if any) → org/mitre
4. Append .json → org/mitre.json
5. Prepend registry/{type}/ → registry/advisory/org/mitre.json

Match Nodes — The Pattern Tree

"match_nodes": [
  {
    "patterns": ["(?i)^cve$"],
    "description": "Common Vulnerabilities and Exposures",
    "weight": 100,
    "data": {
      "url": "https://www.cve.org/CVERecord?id={id}",
      "examples": ["CVE-2024-1234", "CVE-2021-44228"]
    },
    "children": [
      {
        "patterns": ["^CVE-\\d{4}-\\d{4,}$"],
        "description": "Standard CVE ID format",
        "weight": 100,
        "data": {
          "url": "https://www.cve.org/CVERecord?id={id}",
          "examples": [
            {"input": "CVE-2021-44228", "url": "https://www.cve.org/CVERecord?id=CVE-2021-44228"}
          ]
        }
      }
    ]
  }
]

Parent = the source name. Children = specific ID patterns. {id} = variable substitution.

Regex Rules

All patterns must be:

• Anchored: ^pattern$ — no partial matches
• Case-insensitive where appropriate: (?i)^cve$ for source names
• Case-sensitive for IDs: ^CVE-\d{4}-\d{4,}$ — preserve source format
• No catastrophic backtracking: avoid nested quantifiers like (a+)+

Test your patterns:

# Quick test in Python (works everywhere)
import re
assert re.match(r"^CVE-\d{4}-\d{4,}$", "CVE-2021-44228")
assert not re.match(r"^CVE-\d{4}-\d{4,}$", "CVE-bad")

See docs/guides/REGEX-WORKFLOW.md for the full testing workflow.

Adding a New Namespace — Step by Step

1. Determine the type — advisory, weakness, ttp, control, capability, methodology, disclosure, regulation, entity, reference

2. Compute the file path:

example.com → registry/{type}/com/example.json

3. Check if it exists — if so, add a source section (match_node) to it

4. If new, use an existing entry as a reference:

# Copy a similar entry and adapt it
cp registry/advisory/com/redhat.json registry/advisory/com/example.json
# Edit with the real data

5. Fill in: urls, match_nodes (patterns, descriptions, examples)

6. Validate:

python3 -c "import json; json.load(open('registry/advisory/com/example.json'))"

7. Submit a PR — one logical change, descriptive commit message

What Makes a Good Entry

Essential:

• namespace matches the file path (reverse-DNS algorithm)
• type is one of the 10 valid types
• match_nodes have anchored regex patterns
• data.url has a working URL template with {id} variable
• data.examples include real, verifiable identifiers

Good to have:

• description explains what the source is in one sentence
• Multiple examples covering common ID formats
• children for hierarchical ID systems (subpath patterns)
• Structured ExampleObject entries with {input, url} for test fixtures

Avoid:

• Unanchored patterns (missing ^ or $)
• Patterns that match too broadly
• URLs that don't actually work

Research Workflow for New Sources

Pass 1: Identify the source (10 min)

• What does it publish? (advisories, controls, techniques, etc.)
• Who publishes it? (organization's domain name)
• What are the identifier formats? (CVE-YYYY-NNNN, CWE-NNN, etc.)
• Where do items resolve to? (URL patterns)

Pass 2: Document patterns (15 min)

• Write regex patterns for the ID formats
• Build URL templates with {id} substitution
• Gather 3-5 real examples to test with

Pass 3: Validate (5 min)

• JSON parses correctly
• Patterns match the examples
• URLs work when you substitute real IDs
• Patterns DON'T match things they shouldn't

AI agents can help with all of these. The MCP server + registry-research skill are designed for this.

Common Patterns to Follow

Look at existing entries for your type:

Copy the structure, change the content. Don't invent new patterns.

The Contribution Process

1. Open an issue (optional but recommended for new sources)
      ↓
2. Fork the repo
      ↓
3. Create your file(s) following the format
      ↓
4. Validate JSON + test regex patterns
      ↓
5. Submit a PR with a descriptive commit message
      ↓
6. CSA reviews (regex safety, URL validity, format)
      ↓
7. Merge → auto-deploys to live resolver

PRs that modify regex patterns: include a note about regex safety (anchored, no backtracking).

One logical change per PR. "Add EUVD advisory namespace" not "add 10 random things."

Participation: Beyond PRs

Self-service: You maintain your own namespace files. CSA maintains the spec and infrastructure.

Federation: Your resolver is discoverable by other SecID clients. Same protocol, your data.

See docs/proposals/PARTICIPATION-MODEL.md for the full proposal.

How AI Agents Help

AI agents are first-class contributors. The registry is designed to be AI-writable:

• Research: agent browses the source's website, identifies ID formats, writes patterns
• Validation: agent tests patterns against real examples, checks URLs
• Formalization: agent converts rough notes into properly formatted JSON
• Review: agent checks regex safety, format compliance, cross-references

Tools available:

• MCP server for looking up existing entries
• skills/registry-research/ for research workflow
• skills/registry-validation/ for validation checks
• Claude Code plugin for integrated workflow

The human decides what to add. The AI does the mechanical work.