diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..8f9bf99 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,79 @@ +name: Bug report +description: Report reproducible incorrect behavior, a crash, or an installation failure. +title: "[Bug]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thank you for the report. Do not include vulnerabilities, credentials, tokens, private source, or customer data. Security reports belong in the private advisory form. + - type: checkboxes + id: checks + attributes: + label: Preflight + options: + - label: I searched existing issues and did not find this bug. + required: true + - label: This report does not contain a security vulnerability or sensitive data. + required: true + - type: input + id: version + attributes: + label: PatchFlow version + description: Paste the output of `patchflow version`. + placeholder: patchflow v0.1.6 ... + validations: + required: true + - type: dropdown + id: installation + attributes: + label: Installation method + options: + - Release binary or install script + - Homebrew + - Scoop + - Container + - go install + - Built from source + - Other + validations: + required: true + - type: input + id: platform + attributes: + label: Platform + description: Operating system, architecture, and relevant shell. + placeholder: Ubuntu 24.04, amd64, bash + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal reproduction + description: Provide exact redacted commands and the smallest public fixture or repository that reproduces the problem. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + validations: + required: true + - type: textarea + id: logs + attributes: + label: Redacted diagnostics + description: Include relevant output only after removing tokens, credentials, source, private paths, and personal data. + render: text + - type: textarea + id: regression + attributes: + label: Regression information + description: If known, identify the last working version or commit. diff --git a/.github/ISSUE_TEMPLATE/community_question.yml b/.github/ISSUE_TEMPLATE/community_question.yml new file mode 100644 index 0000000..4f503e2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/community_question.yml @@ -0,0 +1,42 @@ +name: Community question +description: Ask for non-sensitive help with installation, configuration, usage, or contribution. +title: "[Question]: " +labels: + - question +body: + - type: checkboxes + id: checks + attributes: + label: Preflight + options: + - label: I checked README.md, SUPPORT.md, and the command documentation. + required: true + - label: This question contains no vulnerability details, secrets, tokens, private source, or personal data. + required: true + - type: input + id: version + attributes: + label: PatchFlow version + placeholder: Output of patchflow version, or not installed yet + validations: + required: true + - type: input + id: platform + attributes: + label: Platform and installation method + placeholder: macOS arm64 / Homebrew + validations: + required: true + - type: textarea + id: goal + attributes: + label: What are you trying to accomplish? + validations: + required: true + - type: textarea + id: attempted + attributes: + label: What have you tried? + description: Include redacted commands and output. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..ccf85b8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Private security report + url: https://github.com/Patchflow-security/patchflow-cli/security/advisories/new + about: Report vulnerabilities privately. Do not disclose exploit details in a public issue. + - name: Support guide + url: https://github.com/Patchflow-security/patchflow-cli/blob/main/SUPPORT.md + about: Choose the correct channel for questions, bugs, false positives, and commercial support. diff --git a/.github/ISSUE_TEMPLATE/false_positive.yml b/.github/ISSUE_TEMPLATE/false_positive.yml new file mode 100644 index 0000000..719887a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/false_positive.yml @@ -0,0 +1,73 @@ +name: False positive +description: Report a finding that is incorrect or creates avoidable scanner noise. +title: "[False positive]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Use synthetic or public code only. Never paste private source, real secrets, or an undisclosed vulnerability. + - type: checkboxes + id: checks + attributes: + label: Preflight + options: + - label: I searched for an existing report with the same rule and pattern. + required: true + - label: The reproducer is safe to publish and contains no sensitive data. + required: true + - type: input + id: version + attributes: + label: PatchFlow version + placeholder: Output of patchflow version + validations: + required: true + - type: input + id: rule + attributes: + label: Rule or finding ID + placeholder: G404, PY001, framework rule ID, CVE, or secret pattern + validations: + required: true + - type: input + id: command + attributes: + label: Command and profile + placeholder: patchflow scan run --profile standard + validations: + required: true + - type: textarea + id: fixture + attributes: + label: Minimal public fixture + description: Provide the smallest vulnerable-looking but safe example and its language/framework. + render: text + validations: + required: true + - type: textarea + id: reasoning + attributes: + label: Why this is a false positive + description: Identify the sanitizer, safe API, control flow, context, or rule assumption that makes the finding incorrect. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected detection behavior + description: Explain what should be suppressed and what nearby genuinely vulnerable pattern must still be detected. + validations: + required: true + - type: textarea + id: noise + attributes: + label: Noise impact + description: Estimate frequency or provide redacted counts if this affects more than one finding. + - type: checkboxes + id: suppression + attributes: + label: Temporary suppression + options: + - label: I confirmed whether a documented `patchflow:ignore` directive is an acceptable temporary workaround. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..2dc5200 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,51 @@ +name: Feature request +description: Propose a user outcome or workflow improvement for PatchFlow CLI. +title: "[Feature]: " +labels: + - enhancement +body: + - type: checkboxes + id: checks + attributes: + label: Preflight + options: + - label: I searched existing issues and the current command documentation. + required: true + - type: textarea + id: problem + attributes: + label: Problem + description: Describe the user problem without prescribing an implementation. + validations: + required: true + - type: textarea + id: outcome + attributes: + label: Desired outcome + description: What should a user be able to accomplish, and how would success be measured? + validations: + required: true + - type: textarea + id: workflow + attributes: + label: Current workflow and alternatives + description: Show the current commands or workarounds and why they are insufficient. + validations: + required: true + - type: textarea + id: interface + attributes: + label: Proposed CLI or output contract + description: Optional example flags, JSON/SARIF fields, exit codes, or configuration. + - type: textarea + id: privacy + attributes: + label: Local-first, privacy, and security impact + description: Identify any source upload, network call, credential, sandbox, or trust-boundary change. + validations: + required: true + - type: textarea + id: compatibility + attributes: + label: Compatibility and performance impact + description: Note platform, schema, runtime, binary-size, benchmark, or migration concerns. diff --git a/.github/ISSUE_TEMPLATE/rule_request.yml b/.github/ISSUE_TEMPLATE/rule_request.yml new file mode 100644 index 0000000..a69a967 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/rule_request.yml @@ -0,0 +1,74 @@ +name: Security rule request +description: Propose a new vulnerability pattern, framework rule, source, sink, or sanitizer. +title: "[Rule]: " +labels: + - enhancement +body: + - type: checkboxes + id: checks + attributes: + label: Preflight + options: + - label: I searched existing rules and requests for this behavior. + required: true + - label: All examples are synthetic or public and safe to disclose. + required: true + - type: input + id: ecosystem + attributes: + label: Language and framework + placeholder: Python / FastAPI + validations: + required: true + - type: input + id: weakness + attributes: + label: Weakness classification + description: CWE, OWASP category, or a concise vulnerability class. + placeholder: CWE-89 SQL Injection + validations: + required: true + - type: textarea + id: threat + attributes: + label: Threat and user impact + description: Explain the trust boundary, attacker-controlled input, sink, and realistic impact. + validations: + required: true + - type: textarea + id: vulnerable + attributes: + label: Vulnerable fixture + render: text + validations: + required: true + - type: textarea + id: safe + attributes: + label: Safe control fixture + description: Show a sanitizer, safe API, or pattern that must not produce a finding. + render: text + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed detection contract + description: Suggest sources, sinks, sanitizers, file types, severity, message, and limitations. + validations: + required: true + - type: textarea + id: references + attributes: + label: Authoritative references + description: Link vendor documentation, a CWE, advisory, or framework security guidance. + - type: dropdown + id: contribution + attributes: + label: Contribution interest + options: + - I can open a pull request with rule and fixtures + - I can help test a proposed rule + - I am requesting maintainer implementation + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..5627bd9 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,43 @@ +## Outcome + +Describe the user/developer problem and the outcome delivered by this pull request. + +## Scope + +- Included: +- Explicitly not included: +- Compatibility or migration notes: + +## Verification + +List exact commands and results. Explain every intentional skip. + +- [ ] `go mod tidy` leaves `go.mod` and `go.sum` unchanged. +- [ ] `gofmt` produces no diff. +- [ ] `go vet ./...` passes. +- [ ] Relevant focused tests pass. +- [ ] `go test ./... -timeout 10m` passes. +- [ ] `go build ./...` passes. +- [ ] User-facing documentation is updated when behavior or output changes. + +## Rule, noise, and benchmark impact + +- Finding/rule IDs affected: +- Vulnerable fixture added or updated: +- Safe control fixture added or updated: +- False-positive/false-negative impact: +- Runtime, memory, binary-size, or benchmark impact: +- If not applicable, explain why: + +## Security and privacy + +- [ ] No real secrets, tokens, private source, customer data, or personal data are included. +- [ ] New network calls, credential access, source upload, and trust-boundary changes are documented. +- [ ] Machine-readable output remains valid and logs do not corrupt stdout. +- [ ] Security-sensitive details were reported privately instead of included here. + +## Contribution + +- [ ] Commits include a DCO `Signed-off-by` trailer (`git commit -s`). +- [ ] I have read `CONTRIBUTING.md` and followed the Code of Conduct. +- [ ] Related issue(s): diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..13fe7ab --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,124 @@ +# Contributing to PatchFlow CLI + +Thank you for helping improve PatchFlow CLI. Contributions may include bug +fixes, false-positive reductions, framework rules, fixtures, documentation, +performance work, and product proposals. + +Please follow the [Code of Conduct](CODE_OF_CONDUCT.md) in every project space. +Security vulnerabilities must follow [SECURITY.md](SECURITY.md), not a public +issue or pull request. + +## Before you start + +- Search [existing issues](https://github.com/Patchflow-security/patchflow-cli/issues) + and pull requests. +- Use the issue chooser for a bug, false positive, rule request, feature request, + or community question. +- For a large change, open an issue before implementation so maintainers can + confirm the contract and review scope. +- Keep a pull request focused on one outcome. Generated formatting, unrelated + cleanup, and behavior changes should not be mixed without explanation. + +## Development setup + +Prerequisites: + +- Git; +- Go `1.26.4` as declared by `go.mod`; +- optional scanner binaries only when the affected integration requires them. + +```bash +git clone https://github.com/Patchflow-security/patchflow-cli.git +cd patchflow-cli +go mod download +go build -o patchflow . +./patchflow version +``` + +Run the same core checks used by CI: + +```bash +go mod tidy +git diff --exit-code -- go.mod go.sum +gofmt -w . +go vet ./... +go test ./... -timeout 10m +go build ./... +``` + +`go test ./...` includes integration packages that may be slower locally. When +iterating, run the affected package first, then run the complete suite before +requesting review. See [the development guide](docs/DEVELOPMENT.md) and +[developer guide](docs/DEVELOPER_GUIDE.md) for architecture and conventions. + +## Pull-request workflow + +1. Fork the repository or create a topic branch. +2. Add a focused regression test before or with the fix. +3. Update user-facing documentation when flags, output, rules, or behavior change. +4. Run the core checks above and record any intentional skip. +5. Complete every applicable section of the pull-request template. +6. Respond to review with follow-up commits; do not rewrite another contributor's + branch without permission. + +Pull requests should explain: + +- the user-visible problem and expected outcome; +- compatibility or schema impact; +- security and privacy implications; +- runtime, binary-size, and benchmark impact; +- false-positive/false-negative or other noise impact; +- the exact commands used for verification. + +## Adding or changing a security rule + +Framework packs live under `internal/sast/frameworks//`. Follow the +[framework pack contract](internal/sast/frameworks/README.md): + +1. Declare the typed rule, source, sink, sanitizer, and safe patterns. +2. Register a new pack in `default_registry.go` and add detection signals when + introducing a framework. +3. Start new rule packs as `experimental` until their fixture suite passes. +4. Add vulnerable, safe, and normal fixtures. A rule is incomplete if it only + proves that a vulnerable example matches. +5. Assert stable rule ID, severity, location, message, and suppression behavior. +6. Measure changes in findings and runtime against the relevant benchmark or + explain why no benchmark is applicable. + +Do not include real credentials, private repositories, proprietary source, or +unredacted customer findings in fixtures. Use unmistakably synthetic secrets and +minimal source examples. + +## Fixtures and false positives + +- Put fixtures next to the package or in its existing test fixture directory. +- Include the smallest code needed to reproduce the behavior. +- Pair every vulnerable fixture with at least one safe control. +- Cover framework aliases, file extensions, sanitizers, and suppression comments + when relevant. +- A false-positive fix must retain a test showing that the genuinely vulnerable + pattern is still detected. + +## Commit sign-off (DCO) + +PatchFlow uses the [Developer Certificate of Origin 1.1](https://developercertificate.org/) +instead of a separate Contributor License Agreement. Sign off each commit to +certify that you have the right to submit it: + +```bash +git commit -s -m "fix: describe the change" +``` + +This adds a `Signed-off-by: Name ` trailer matching the commit author. +If a commit is missing the trailer, amend it before requesting review. A future +CLA or sign-off policy change requires the governance process in +[GOVERNANCE.md](GOVERNANCE.md); it will not apply silently. + +## Review and merge + +Passing automation is necessary but not sufficient. A maintainer reviews the +contract, tests, security impact, and documentation. Maintainers may request a +smaller scope, additional fixtures, or benchmark evidence. Merge and release +authority is defined in [GOVERNANCE.md](GOVERNANCE.md). + +For help choosing the correct channel, see [SUPPORT.md](SUPPORT.md). diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..708b52f --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,79 @@ +# Governance + +PatchFlow CLI uses lightweight maintainer governance intended to keep technical +decisions reviewable while the contributor community grows. + +## Roles + +| Role | Responsibilities | How the role is obtained | +| --- | --- | --- | +| User | Uses the CLI and provides feedback | Open to everyone | +| Contributor | Submits issues, code, rules, fixtures, docs, or reviews | Any accepted participation under the Code of Conduct | +| Maintainer | Triages, reviews, merges, moderates, and stewards an area | Invited by consensus of current maintainers after sustained trusted contribution | +| Release maintainer | Creates tags/releases and verifies provenance and artifacts | Explicit delegation by organization owners | +| Security maintainer | Receives private reports and coordinates advisories | Explicit delegation with repository security access | + +The current organization owner and initial maintainer is +[@malik111110](https://github.com/malik111110). Repository permissions are the +authoritative record of current merge, release, and security access. + +## Decisions + +Routine changes use the normal issue and pull-request process. A maintainer may +merge once required checks pass, review feedback is resolved, and the change has +the necessary approval under branch protection. + +Open a public design issue or architecture decision record for changes that: + +- break CLI flags, configuration, output schemas, rule IDs, or exit codes; +- change local-first/privacy behavior or source upload boundaries; +- add a required network service or external scanner; +- alter licensing, contribution terms, governance, release provenance, or the + supported platform matrix; +- create substantial false-positive, performance, or binary-size risk. + +The issue should state the user outcome, alternatives, compatibility plan, +security/privacy impact, evidence, and rollback. Maintainers seek rough +consensus; when consensus is not possible, the organization owner records the +decision and rationale publicly. Security-sensitive details may be decided in a +private advisory and summarized after disclosure. + +## Review and merge authority + +- Authors do not approve their own pull requests when another maintainer is + available. +- Required CI and review rules may not be bypassed for convenience. +- Emergency security fixes may use a private fork/advisory, but the public + history, advisory, tests, and release provenance are reconciled after release. +- Force-pushes to protected default and release branches are prohibited. +- Maintainers may close stale or out-of-scope proposals with a reason and a path + to reconsideration. + +## Releases + +Release maintainers are the only role authorized to create official tags and +publish GitHub/GHCR/Homebrew/Scoop artifacts. A release must originate from a +reviewed public commit, pass the release workflow, use the versioning and +compatibility policy in `RELEASE.md`, and publish checksums/provenance required by +the release configuration. + +No date or feature commitment is binding until it appears in a published release. + +## Becoming or leaving a maintainer + +A nomination should cite sustained contributions, sound review judgment, +security awareness, respectful conduct, and availability. Existing maintainers +record the decision in a public issue unless privacy or safety requires a private +record. Access follows least privilege and is reviewed when responsibilities +change. + +Maintainers may step down at any time. Inactive access may be removed after an +attempt to contact the maintainer. Conduct violations or security abuse may lead +to immediate suspension by organization owners, followed by a documented review. + +## Governance changes + +Changes to this document require a dedicated pull request, public rationale, and +approval from the organization owner plus any other active maintainer. The +change takes effect only after merge; contribution or licensing terms do not +change retroactively without explicit legal review. diff --git a/README.md b/README.md index c5c7193..fed1a1f 100644 --- a/README.md +++ b/README.md @@ -259,6 +259,16 @@ patchflow scan changed --json By default, the CLI sends only metadata (file paths, branch names, diff stats). It does not send source code contents unless explicitly configured. +Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md), +not a public issue. + +## Community + +- [Contributing guide](CONTRIBUTING.md) +- [Support channels](SUPPORT.md) +- [Governance](GOVERNANCE.md) +- [Code of Conduct](CODE_OF_CONDUCT.md) + ## Examples ### Authenticate diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..2bd6e6a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,73 @@ +# Security policy + +PatchFlow CLI is a security tool. Please report vulnerabilities privately so +users can receive a fix before exploit details are public. + +## Supported versions + +| Version | Security support | +| --- | --- | +| Latest published release series | Supported | +| Earlier release series | Upgrade required unless a maintainer announces an exception | +| `main` and unreleased snapshots | Best effort; not a supported production release | + +The current release is listed on the +[GitHub releases page](https://github.com/Patchflow-security/patchflow-cli/releases/latest). + +## Private reporting + +Use GitHub's private vulnerability reporting form: + +**[Report a vulnerability privately](https://github.com/Patchflow-security/patchflow-cli/security/advisories/new)** + +Do not disclose the vulnerability in a public issue, discussion, pull request, +commit message, benchmark, or fixture. If the form is unavailable, contact a +Patchflow-security organization owner through an existing private channel and +ask for a private advisory to be opened; do not send exploit details publicly. + +Include when possible: + +- affected version, platform, and installation method; +- vulnerability class and realistic impact; +- minimal reproduction or proof of concept; +- whether untrusted repository content is required; +- logs with tokens, source, credentials, paths, and personal data removed; +- suggested remediation and disclosure constraints. + +Examples in scope include arbitrary command execution, path traversal, unsafe +archive handling, secret leakage, authentication/token compromise, malicious +repository content escaping expected boundaries, report tampering, and release +artifact or update-channel compromise. A scanner false positive without a +security boundary impact belongs in the false-positive issue form. + +## Response targets + +These are service targets, not guarantees: + +| Stage | Target | +| --- | --- | +| Initial acknowledgement | 2 business days | +| Reproduction and severity triage | 5 business days | +| Status update while unresolved | At least every 7 calendar days | +| Fix/disclosure plan | As soon as impact is understood | + +Urgent actively exploited reports are prioritized immediately. Timing depends on +severity, affected releases, downstream coordination, and reporter availability. + +## Coordinated disclosure + +PatchFlow maintainers will validate the report, agree on severity and scope, +prepare a fix and regression test, and coordinate publication with the reporter. +The default disclosure target is within 90 days, but it may be shortened for +active exploitation or extended by mutual agreement for ecosystem coordination. + +A public advisory should credit the reporter if requested, identify affected and +fixed versions, explain mitigations, and avoid unnecessary exploit detail. Please +allow maintainers to publish a fixed release before public disclosure. + +## Safe-harbor intent + +Good-faith research that avoids privacy violations, service degradation, +unauthorized persistence, data destruction, and access beyond what is necessary +to demonstrate the issue will not be treated as malicious by the project. This +statement does not authorize testing systems or data that PatchFlow does not own. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..47edf90 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,45 @@ +# Support + +Choose the channel that matches the request. Public GitHub issues are visible to +everyone: never include source code, tokens, credentials, private repository +names, customer data, or security exploit details. + +## Community help + +Use the +[community question form](https://github.com/Patchflow-security/patchflow-cli/issues/new?template=community_question.yml) +for installation, configuration, output interpretation, or contribution help. +Community support is best effort. Include `patchflow version`, operating system, +installation method, redacted command, and expected outcome. + +## Bugs and false positives + +- Use the [bug form](https://github.com/Patchflow-security/patchflow-cli/issues/new?template=bug_report.yml) + for crashes, incorrect behavior, broken installation, or output-contract errors. +- Use the [false-positive form](https://github.com/Patchflow-security/patchflow-cli/issues/new?template=false_positive.yml) + when a finding is technically incorrect or too noisy. +- Use the [rule request form](https://github.com/Patchflow-security/patchflow-cli/issues/new?template=rule_request.yml) + for a new vulnerability pattern or framework rule. +- Use the [feature request form](https://github.com/Patchflow-security/patchflow-cli/issues/new?template=feature_request.yml) + for a new product capability or workflow. + +Reproducible reports with a minimal public fixture receive the fastest response. + +## Security vulnerabilities + +Do not open a public issue. Follow [SECURITY.md](SECURITY.md) and use +[private vulnerability reporting](https://github.com/Patchflow-security/patchflow-cli/security/advisories/new). + +## Commercial support + +Customers with a support agreement should use the private channel and response +targets named in that agreement. Prospective users may open a feature request to +describe a non-confidential requirement; maintainers will move commercial or +sensitive follow-up to an appropriate private channel. Public issue response +times are not commercial support commitments. + +## Conduct and moderation + +Community conduct reports follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). +General support and security reporting channels must not be used to publish +harassment reports or private personal information.