Contributing Security Issue Tracking

Contributing, Security & Issue Tracking

This page details the governance and collaboration protocols for the Claude Sleuth project. It covers the technical workflow for contributors, the coordinated disclosure process for security vulnerabilities, and the structured formats for reporting bugs or requesting new intelligence capabilities.

Contribution Workflow

The project follows a structured contribution model to ensure code quality and maintainability across the 56-task intelligence pipeline. Contributors are expected to use atomic commits and adhere to specific branching conventions.

Branching Strategy

The repository enforces a strict branching model to separate stable code from work-in-progress features:

Branch Prefix	Purpose	Target
main	Stable, production-ready code. Protected branch.	N/A
feature/	New intelligence skills, scripts, or CLI enhancements.	main
fix/	Bug fixes for existing tools or task runner logic.	main
docs/	Updates to wiki pages, templates, or inline documentation.	main

Development Lifecycle

The following diagram illustrates the transition from a local environment setup to a Pull Request.

Contributor Workflow: Local to PR

graph TD
    subgraph "Local_Environment"
        A["Fork & Clone Repo"] --> B["python -m venv .venv"]
        B --> C["pip install -e '.[all]'"]
        C --> D["git checkout -b feature/name"]
    end

    subgraph "Development_Cycle"
        D --> E["Atomic Commits (Imperative Mood)"]
        E --> F["Push to Fork"]
    end

    subgraph "GitHub_Review"
        F --> G["Open Pull Request to main"]
        G --> H{"CI Checks Pass?"}
        H -- "Yes" --> I["Maintainer Review"]
        H -- "No" --> E
        I --> J["Merged to main"]
    end

Loading

Pull Request Requirements

To maintain the integrity of the investigative toolkit, all PRs must meet the following criteria:

• Focus: One feature or fix per PR to simplify the review of complex intelligence scripts [.github/CONTRIBUTING.md:55-55].
• Traceability: Reference related issues using Closes #<issue-number> [.github/CONTRIBUTING.md:54-54].
• Synchronization: Branches must be rebased or merged with main before review [.github/CONTRIBUTING.md:56-56].

Security Policy

The Claude Sleuth project takes security seriously, particularly regarding data handling in the MCP server and the execution of external intelligence scripts.

Vulnerability Disclosure Process

Do not open public GitHub issues for security vulnerabilities. The project follows a coordinated disclosure timeline to ensure fixes are deployed before the vulnerability is publicized.

Milestone	SLA / Timeline
Acknowledgement	Within 48 hours of receipt
Initial Assessment	Within 5 business days
Coordinated Disclosure	Agreed timeline prior to public announcement

Reporting Requirements

Reports should be sent to elb.pr.contact@gmail.com and must include:

1. Description of the vulnerability and potential impact.
2. Steps to reproduce (PoC code or screenshots).
3. Suggested severity rating (Critical, High, Medium, Low).

Security Scope

The policy covers the core toolkit and its persistent database layer.

Security Domain Mapping

graph LR
    subgraph "In_Scope"
        A["claude-sleuth Source Code"]
        B["Dependency Exploitation Risk"]
        C["MCP Server Data Handling"]
    end

    subgraph "Out_of_Scope"
        D["Third-party OSINT Services"]
        E["Physical Machine Access"]
    end

    A --- F["Security Policy"]
    B --- F
    C --- F
    D --- G["External Risk"]
    E --- G

Loading

Issue Tracking

The project uses structured GitHub Issue Templates to ensure that bug reports and feature requests contain the necessary technical context for debugging or implementation.

Bug Reports

Bug reports require environment-specific details to help maintainers reproduce issues across different OS and Python versions.

Field	Requirement
Description	Clear and concise summary of the unexpected behavior [.github/ISSUE_TEMPLATE/bug_report.md:9-11].
Environment	OS, Python version, and claude-sleuth version [.github/ISSUE_TEMPLATE/bug_report.md:31-35].
Installation	Method (pip install -e .) and dependency groups installed (network, geo, etc.) [.github/ISSUE_TEMPLATE/bug_report.md:36-37].
Evidence	Error messages, stack traces, and relevant logs [.github/ISSUE_TEMPLATE/bug_report.md:23-29].

Feature Requests

Feature requests are framed around investigative utility and the "Intelligence Cycle."

• Problem Statement: Identify the gap in the current 56-task pipeline [.github/ISSUE_TEMPLATE/feature_request.md:9-11].
• Proposed Solution: Specific technical details (e.g., new CLI flags for sleuth-task or new modules for setup.py) [.github/ISSUE_TEMPLATE/feature_request.md:13-15].
• Use Case: A concrete investigative scenario where the feature would be applied (e.g., "Corporate intelligence during Phase 3") [.github/ISSUE_TEMPLATE/feature_request.md:21-23].

---