OX Security GitHub App Permissions

OX Security connects to GitHub through a GitHub App that scans your code and, optionally, acts on your behalf to remediate findings. OX offers two variants of the GitHub App, and this page covers both.

OX follows the principle of least privilege. Every write the app performs is initiated by an explicit action in the OX UI. OX never modifies your repositories or organization silently.

Which variant should you install?

If you want OX to...	Install the...
Scan your code, surface findings in the OX UI, and let your team handle remediation manually	Read-only variant
Scan your code AND take action on your behalf, including opening auto-fix pull requests, posting PR comments and reviews, and remediating posture issues when you accept the fix in the OX UI	Read + write variant (default)

Capability comparison

Capability	Read-only	Read + write
Code scanning (SAST, SCA, IaC, secret scanning)	Yes	Yes
OX Security PR status check	Yes	Yes
PR-aware scanning and code-review policies	Yes	Yes
Ingest Dependabot, secret-scanning, and CodeQL findings	Yes	Yes
Posture findings (branch protection, Actions, RBAC, webhooks)	Detection only	Detection and remediation
One-click auto-fix pull requests	No	Yes
Inline PR review comments on findings	No	Yes
OX summary comment on pull requests	No	Yes
Remediation of branch protection, repo settings, Actions permissions, and collaborator membership	No	Yes
Clean uninstall from the OX UI	No	Yes

Status definitions

• Required: OX can't function without this permission.

• Optional: A specific OX feature becomes unavailable, but the rest of the platform continues to work.

• Reserved: OX requests this permission for an upcoming capability. Denying it has no impact on current functionality.

Permissions at a glance

Permission	Read-only variant	Read + write variant	Status
Metadata	Read	Read	Required
Code (contents)	Read	Read and write	Required (read), Optional (write)
Checks	Read and write	Read and write	Optional
Pull requests	Read	Read and write	Optional (high value)
Issues	Read	Read and write	Optional
Actions	Read	Read and write	Optional
Administration	Read	Read and write	Optional
Members	Read	Read and write	Optional
Organization administration	Read	Read and write	Optional
Workflows	Not requested	Write	Optional (read + write variant only)
Dependabot alerts	Read	Read	Optional
Secret scanning alerts	Read	Read	Optional
Security events	Read	Read	Optional
Repository hooks	Read	Read	Optional
Commit statuses	Read	Read	Reserved
Deployments	Read	Read	Reserved
Pages	Read	Read	Reserved
Packages	Read	Read	Reserved
Repository projects	Read	Read	Reserved
Custom repository roles	Read	Read	Reserved
Organization events	Read	Read	Reserved
Organization hooks	Read	Read	Reserved
Organization projects	Read	Read	Reserved
Organization self-hosted runners	Read	Read	Reserved
Organization user blocking	Read	Read	Reserved

Required permissions

These are the minimum permissions OX needs to scan your code. Both variants request the same required permissions.

Permission	Read-only variant	Read + write variant	Why you need it	If you don't grant this
Metadata	Read	Read	So OX can find the repositories you've authorized and read basic repository information. GitHub requires this baseline permission for nearly every API endpoint.	OX can't see any repository, and no part of the product works.
Code (contents)	Read	Read (required), write (optional)	Read is the foundation of every code scan OX runs (SAST, SCA, IaC, secret scanning). In the read + write variant, write also lets OX open one-click auto-fix pull requests on your behalf by creating a branch, committing the proposed fix, and opening a PR for your team to review and merge.	Without read: all code-based scanning stops. Without write (read + write variant only): auto-fix PRs can't be opened. Scanning continues and findings still appear in OX, but the Fix button on a finding won't work.

Optional permissions

Optional permissions fall into two groups, based on whether the two variants request the same access level or not.

Group 1: Optional permissions that work the same in both variants

For these permissions, both variants request identical access. Read-only ingests external signals into OX. Checks is the only write permission requested by both variants, and it powers the OX Security PR status check.

Permission	Access	Why you need it	If you don't grant this
Checks	Read and write	So developers see OX findings directly on every pull request and you can gate merges on the OX Security check. This is the only write permission the read-only variant requests.	Scans still run and findings remain visible in the OX UI. However, no OX status check appears on pull requests, and any merge-gating workflow that depends on the OX check stops working.
Dependabot alerts	Read	So GitHub's native Dependabot findings appear alongside OX's own SCA results in a single dashboard, giving you one place to triage vulnerable dependencies.	Dependabot findings don't appear in OX. The OX SCA scanner still detects vulnerable dependencies on its own.
Secret scanning alerts	Read	So GitHub's native secret-scanning results appear alongside OX's secret scanner, giving you a unified view of leaked secrets.	GitHub-native secret-scanning findings don't appear in OX. The OX secret scanner continues to operate.
Security events	Read	So CodeQL and any third-party SARIF findings uploaded to GitHub appear in OX, consolidating all your SAST results in one place.	GitHub Code Scanning, CodeQL, and SARIF-uploaded findings don't appear in OX. The OX SAST scanner continues to scan your code independently.
Repository hooks	Read	So OX can detect insecure webhooks that could leak repository data (for example, webhook URLs without SSL verification).	Webhook posture findings become unavailable.

Group 2: Optional permissions where the read + write variant adds write access

For these permissions, the read-only variant requests read access only. The read + write variant requests the same read access, plus additional write access that lets OX act on your behalf when you accept a fix in the OX UI.

The two columns below split each permission cleanly: what read access powers (detection, available in both variants) and what write access adds (remediation, available only in the read + write variant).

Permission	Read access powers detection (both variants)	Write access adds remediation (read + write variant only)
Pull requests	Per-PR scanning, code-review policy posture (for example, Pull request merged without review), and accurate attribution of who introduced a finding.	Opens auto-fix pull requests, posts inline review comments at the exact file and line of a finding, requests reviewers, and updates or dismisses past reviews as findings evolve.
Issues	Comment deduplication when OX posts findings on pull requests, keeping the PR conversation clean.	Posts and updates the OX summary comment on a pull request. GitHub treats top-level PR comments as "issue comments".
Actions	GitHub Actions and CI/CD posture findings (insecure third-party actions, fork pull request workflow rules, overly permissive Actions tokens).	One-click remediation of Actions misconfigurations: restrict default workflow permissions to read-only, disable workflow approval of pull requests.
Administration	Branch protection and ruleset compliance findings (Branch lacks required reviews, Rulesets bypassable by admins).	One-click remediation of branch protection rules and repository settings: require reviews, require signed commits, disallow deletion or force pushes, set repo private, archive, disallow forking.
Members	RBAC and access-control findings: outside collaborators, admin sprawl, missing two-factor authentication enforcement.	Removes a collaborator or changes a collaborator's permission level (pull, triage, push, maintain, admin).
Organization administration	Org-level audit-log analysis and discovery of installed apps.	Removes an organization member or changes their org role, flips the org-level Allow forking of private repositories setting, and cleanly uninstalls the OX GitHub App when you disconnect from the OX UI.

If you decline read access: the detection capability in that row stops working. Code scanning continues for everything else.

If you decline write access (read + write variant only): the remediation capability in that row stops working. Detection still works, and your team can apply the fix manually using the guidance in the OX UI.

Workflows: write access in the read + write variant only

GitHub treats workflow files (.github/workflows/*.yml) as a separate scope and doesn't define a read level for it. The read-only variant doesn't request this permission.

Permission	Access (read + write variant)	Why you need it	If you don't grant this
Workflows	Write	So OX's auto-fix pull requests can include changes to workflow files (for example, bumping an action version as part of an SCA fix).	Auto-fix PRs that touch workflow files are rejected by GitHub. Auto-fix PRs that don't touch workflow files continue to work.

Reserved permissions

OX requests the following read-only permissions in both variants to support upcoming capabilities. Denying any of them has no impact on current functionality.

Permission	Access	Future use
Commit statuses	Read	Commit-status posture analysis.
Deployments	Read	Deployment-tracking findings.
Pages	Read	GitHub Pages posture analysis.
Packages	Read	GitHub Packages security analysis.
Repository projects	Read	Repository-projects posture analysis.
Custom repository roles	Read	Custom-role posture analysis on organization custom roles.
Organization events	Read	Organization-event analysis. The organization audit log itself is covered under Organization administration.
Organization hooks	Read	Organization-level webhook posture analysis.
Organization projects	Read	Organization-projects posture analysis.
Organization self-hosted runners	Read	Self-hosted runner security analysis.
Organization user blocking	Read	User-blocking posture analysis.