Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (77 loc) · 5.86 KB

CONTRIBUTING.md

File metadata and controls

105 lines (77 loc) · 5.86 KB
Raw

Contributing to Claude-OSINT

Thanks for considering a contribution. These skills are battle-tested but always improvable. Below is what's most welcome and how to submit changes.

Most-needed contributions

Priority Type Examples
HIGH Vendor product fingerprints we missed Cisco Meraki, Palo Alto Prisma, Zscaler, Cato Networks, Cloudflare One, Tailscale Funnel, VPN appliances
HIGH Modern secret patterns New API key formats from any service (Linear, Loops, Resend, Anthropic Workspace, Vercel deployment tokens, etc.)
HIGH Real-world examples for examples/ End-to-end engagement walk-throughs (anonymized)
HIGH Bug reports Prompts that don't trigger the right skill section, or trigger the wrong one
MEDIUM Sector-specific deep dives Healthcare practitioners, finance practitioners, ICS specialists know their domain better than the starter notes in §47
MEDIUM Wordlist refreshes New paths discovered in the wild
MEDIUM Tooling install one-liners When new tools mature
LOW Translations Non-English versions for international red-team teams
LOW Typo / formatting fixes Always welcome

What we won't accept

  • Active exploitation tradecraft (PoC code, exploit chains, malware, C2 framework guides). These are out of scope for the OSINT-only posture.
  • Internal-network recon (AD, BloodHound, Kerberos). Different domain.
  • Defensive / blue-team detection content (SIEM rules, EDR signatures). Different audience.
  • Anything that could enable unauthorized access (credential lists, harvested PII, real breach corpus content).
  • Sector-specific content that crosses into sensitive operational tradecraft (e.g., specific ICS exploitation techniques).

How to submit changes

  1. Fork the repo on GitHub.
  2. Create a feature branch: git checkout -b feat/add-vendor-fingerprint-zscaler
  3. Make your changes:
    • Edit the relevant SKILL.md file in skills/<skill-name>/SKILL.md.
    • Update CHANGELOG.md under an [Unreleased] heading at the top.
    • If you're adding a new section, also update the README's "What's in the box" tables.
    • If you're adding a new triggerable concept, add a trigger phrase to the YAML frontmatter.
  4. Run the smoke tests locally:
    • Install the modified skill in Claude Code or attach to a Claude.ai project.
    • Run any relevant prompt from tests/smoke-test-prompts.md and verify behavior.
    • If you added a new section, add at least one self-test prompt for it.
  5. Commit with a clear message:
    • Format: <type>(<scope>): <subject>
    • Types: feat, fix, docs, style, refactor, test, chore
    • Examples: feat(arsenal): add Zscaler vendor fingerprint to §16.16, fix(methodology): correct EPSS threshold tier in §28.2, docs(readme): update coverage table for v2.2
  6. Push and open a PR with:
    • Clear description of what changed and why.
    • Reference any related issues.
    • Note any breaking changes (rare; mostly section renumbering).

Style guide

Markdown conventions

  • Use ## for top-level sections (numbered: ## 16. Pre-built Wordlists).
  • Use ### for subsections (numbered: ### 16.13 Copy-Paste Probes).
  • Code blocks must specify language: ```bash, ```python, ```regex etc.
  • Tables for structured data; bulleted lists for unordered enumerations.
  • Bold for emphasis on first mention of a key concept; avoid otherwise.
  • Sentence case for headings (not Title Case).

Voice

  • Direct. "Probe the path." not "You should probably consider probing the path."
  • Operator-facing. Assume the reader is an experienced practitioner; don't over-explain basics.
  • Detectability-aware. When introducing a probe technique, tag its detectability (low/medium/high).
  • Confidence-aware. When introducing a finding pattern, tag its confidence level (TENTATIVE/FIRM/CONFIRMED).
  • Severity-anchored. New finding categories should map to the §9 / §40 severity rubric.

Trigger discipline

When you add a new capability, add at least one trigger phrase to the YAML frontmatter triggers: list. Trigger phrases should be the exact wording a user would type, not the formal name. E.g., kubelet exposed is a better trigger than Kubernetes Kubelet API exposure on port 10250.

Reviewing other PRs

If you have OSINT experience, please review open PRs. Specifically:

  • Vendor fingerprint accuracy — confirm the path / fingerprint pattern works against a real (authorized) target.
  • Severity assignment — does the proposed severity match the §9 rubric and §40 worked examples?
  • Detectability tag — accurate? Conservative?
  • Cross-skill consistency — does a methodology change have a corresponding arsenal reference and vice versa?

Leak guard (client/engagement identifiers)

Hard rule: no real client/engagement identifier ever lands in the public tree. scripts/scan_identifiers.py hashes every 1- and 2-word shingle of every tracked text file and compares against a hashed denylist (scripts/.identifier-denylist.sha256). It runs in CI via .github/workflows/leak-guard.yml on every push and PR, and fails closed if the denylist is missing.

Enable the local pre-commit hook once per clone so you catch it before pushing:

git config core.hooksPath .githooks

To ban a new identifier without committing the plaintext name, add its hash:

printf '%s' "the name" | tr '[:upper:]' '[:lower:]' | shasum -a 256   # paste into scripts/.identifier-denylist.sha256

or drop the plaintext (one per line) in scripts/.identifier-denylist.local — it's gitignored and hashed at runtime, so the name never enters the repo.

License

By contributing, you agree your contributions are released under the MIT License.

Code of conduct

See CODE_OF_CONDUCT.md. Briefly: be excellent to each other.