Skip to main content

Security & Permissions Model

Security is a first-class feature in Ship Guard. This document explains the GitHub permissions we request, why we need them, how your data flows through the system, and how we protect your intellectual property.

🔑 GitHub App Permissions (Scopes)​

Ship Guard operates as a GitHub App with minimal required permissions:

PermissionAccessWhy We Need It
ChecksRead & writeCreate status checks (pass/fail), attach rule results to PRs
Pull requestsRead & writeRead PR metadata/diffs and post review comments with findings
ContentsRead-onlyRead .github/ship-gaurd.yml and changed files for analysis
Commit statuses (optional)ReadDisplay compatibility with legacy status checks tooling
MetadataReadBasic repo metadata (always granted by GitHub Apps)
Email address**Read-onlyRequired to automatically create a Ship Guard user account upon app installation

Data Minimization & Redaction​

  • Diff-only scope: AI checks operate on the PR diff, not the entire repo, unless explicitly scoped via paths.
  • Secret redaction: Built-in filters attempt to redact tokens/keys before any AI call.
  • Size limits: maxFilesPerReview, maxFileSizeKB, maxTokens control exposure and cost.
  • Path controls: Use paths/excludePaths to further narrow inputs.

🧠 RAG (Knowledge Base) Protections​

When using RAG, only the top few relevant document snippets are included:

  • Weighted retrieval ensures authoritative docs (ADRs, security policies) are prioritized.
  • Configurable limits: ragContext.maxDocs (1–10) and similarityThreshold (0.5–1.0).
  • Exclusion support: Place sensitive docs outside configured rag_sources or exclude via globs.

🗃️ Data Retention & Logging​

  • No code storage: We do not store your repository code or complete diffs.
  • Ephemeral processing: PR content is processed in-memory for rule execution.
  • Minimal logs: We log event IDs and rule execution metrics.
  • Retention: Operational metadata retained for a limited period for debugging and abuse prevention.
  • Opt-outs: Contact support to configure stricter retention or SSO-bound access.

🧾 Auditability & Evidence​

  • Check Runs: Canonical, immutable records on each PR.
  • Structured comments: Optional, with line anchors and error codes for traceability.
  • Error codes & tags: Use errorCode and tags for compliance mapping and internal dashboards.

🛡️ IP Protection Commitments​

  • Principle of Least Privilege: Only the minimal GitHub scopes required.
  • Data Minimization: Analyze only changed lines and necessary context.
  • Redaction: Attempted removal of secrets and PII before AI calls.
  • Transport Security: All network communication uses TLS.
  • Model Providers: Industry-standard providers; prompts sanitized; strict token limits.
  • No resale/sharing: We never sell or share your code or prompts with third parties.

⚙️ Security Features You Control​

  • Branch Protection: Require Ship Guard checks to pass before merging.
  • Global Settings (settings):
    • enableAIReviews: Toggle AI usage globally
    • maxFindings, maxFindingsInComment: Prevent noisy output
    • disableComments, disableStatusChecks: Tighten surface area
    • commentTemplates: Standardize wording for audits
  • AI Rule Controls (ai-review parameters):
    • maxTokens, ragContext.maxDocs, similarityThreshold
    • security.allowSensitiveFiles, security.enableContentFiltering, security.maxFilesPerReview

🧪 Validating Your Setup (Checklist)​

  • Confirm only required GitHub scopes are enabled
  • Set branch protection with “Ship Guard” as a required status check
  • Use paths/excludePaths to restrict sensitive areas
  • Set AI safety caps: maxTokens, maxFilesPerReview, and content filtering
  • Keep RAG sources authoritative and non-sensitive
  • Review logs/metadata policy with your security team