CF ContribFlow

Security

Security

Security Posture

ContribFlow must optimize for maintainer trust, contributor safety, and strict human approval for public actions.

The default stance is conservative:

  • No public GitHub actions without explicit user approval.
  • No secrets in model context, worker logs, or repo command output.
  • No repository code execution on the host machine.
  • No draft PR creation when validation fails, unless the user explicitly overrides with a warning.
  • No large or unrelated patches.

Public Action Controls

The platform must require explicit user approval before:

  • Opening a pull request
  • Posting an issue comment
  • Posting a PR comment
  • Pushing commits to a user fork
  • Replying to maintainer review comments

Draft PRs are the default. Public, non-draft PRs are out of MVP scope.

Current CLI PR behavior:

  • contribflow pr --draft --json is dry-run only and must not perform GitHub writes.
  • contribflow pr --draft --yes --json is the explicit approval path.
  • The approved path must still block without an active workspace, patch artifact, and passing sandbox validation result.
  • Agents must ask the user before running the --yes path.

Token Handling

Rules:

  • Store GitHub tokens encrypted at rest.
  • Never expose write tokens to frontend clients.
  • Never pass long-lived GitHub tokens into agent runner workspaces.
  • Prefer short-lived scoped tokens for GitHub write actions.
  • Redact tokens and credentials from logs before persistence.
  • Do not place secrets in environment variables visible to repo commands.

Milestone 2 implementation note:

  • GitHub OAuth access tokens are not persisted.
  • The callback uses the token only to fetch the GitHub profile and verified primary email.
  • The browser receives only an HTTP-only signed session cookie.
  • Future GitHub write actions must add encrypted token storage or short-lived scoped token handling before implementation.

Agent Sandbox

Minimum runner requirements:

  • Isolated workspace per task
  • No host filesystem mounts beyond the task workspace
  • CPU and memory limits
  • Command timeouts
  • Network restrictions by default
  • Workspace cleanup after completion
  • Captured logs with secret redaction

The MVP can start with container isolation. Stronger isolation such as Firecracker can be evaluated later if needed.

Current CLI validation behavior:

  • contribflow validate --json detects validation commands but does not execute target repository code.
  • contribflow validate --run --sandbox docker --json is the only supported execution path.
  • Docker validation mounts only the active workspace, drops capabilities, sets no-new-privileges, applies CPU/memory/process limits, and redacts/truncates command output.
  • Dependency setup is a separate sandbox phase. It may use container network access only for supported lockfile-backed setup commands and never receives host secrets or GitHub credentials.
  • Validation commands run after setup in a separate no-network Docker phase.
  • --sandbox-image may point at a trusted prebuilt image for repositories with native OS dependencies. ContribFlow does not execute arbitrary host setup commands; missing native headers are surfaced as JSON hints such as suggestedSystemPackages.
  • PR creation must remain blocked when Docker is unavailable, commands are only detected, or any validation command fails.

Dependency Install Risk

Before installing dependencies in a target repo, the worker should:

  • Detect package manager and install command.
  • Require a reproducible lockfile for package-manager installs.
  • Show the planned install command when user approval is required.
  • Run dependency installation only inside the sandbox.
  • Timebox dependency installation.
  • Capture installed package metadata where practical.
  • Flag unexpected lockfile changes.

High-risk postinstall scripts should be blocked or surfaced to the user before execution.

Patch Safety

Warn or block when:

  • Changed files exceed user preference.
  • Lines changed exceed user preference.
  • Generated patch touches secrets, credentials, or security-sensitive paths.
  • Generated patch changes license files.
  • Patch includes unrelated formatting churn.
  • Tests fail after changes.
  • No test is added for a code bug without justification.
  • Duplicate PR risk is high.

Audit Logging

Audit events should include:

  • User approvals
  • Auth events
  • GitHub API write actions
  • Worker commands
  • Validation results
  • Patch approvals
  • PR creation events
  • Review response actions
  • Security warnings

Logs must include enough detail to explain what happened without exposing secrets.

Abuse Prevention

Initial controls:

  • Rate-limit PR creation per user and repository.
  • Block mass similar PRs.
  • Flag typo-only campaigns.
  • Require issue context for PRs.
  • Track duplicate PR warnings.
  • Start users at low autonomy.

Quality signals, not raw PR count, should drive product decisions.

GitHub API Reads

Milestone 4 issue discovery performs read-only requests against public GitHub APIs. Optional GITHUB_TOKEN use should be scoped for read-only local development. Tokens must never be committed, logged, or sent to target repository commands.

Source markdown: docs/SECURITY.md