# Welcome to OX Security Platform OX Security prevents risk at the source, eliminating exposures from AI code generation through cloud and runtime, and solving security debt before it ever reaches production. Unlike conventional tools that cannot keep pace with modern, AI-driven development, or cloud-specific solutions that are infrastructure-only, the OX Security platform pinpoints vulnerabilities at creation and remediates runtime exposures at the source. OX Security platform elements: * **OX VibeSec:** A platform-wide capability that prevents vulnerabilities\ in AI-generated code at the moment of creation, making every line secure by design, embedding your security rules and organizational context across your entire SDLC. * **OX Code:** Detects and remediates vulnerabilities based on business-risk prioritization across your entire codebase before production, integrating directly with CI/CD pipelines to enforce security policies and prevent insecure code. * **OX Cloud:** Secures your infrastructure by identifying vulnerabilities at runtime, revolutionizing CNAPP and AppSec for the cloud with a code-centric approach that enables automatic remediation of real-world risks. * **OX Agentic Pentester:** Validates your AppSec posture with agentic testing that emulates human attackers and adapts like real-world threats to ensure accurate risk prioritization and improve the accuracy of defensive efforts.
Get startedCreate an account, create an organization, and get your code repositories connected/files/6rVjjeZYsxC5o8KTbTXe/pages/KiUfE2erbHADN049Kctg
Start scanningLearn about our scanning methods/files/wsp0o3jcsPQQxZsJ9xMd/pages/0KbDdFpwf9JgayTeVN3F
Get connectedIntegrate your development infrastructure and other security tools to make OX your AppSec one-stop-shop/files/yRi8jGGCtE3YLEcfVPKN/pages/i1l2MPZi9aQOeyWoSLsp
# Supported Languages and Frameworks The following is the overview of supported languages across different OX Security categories: * [Code security](#code-security-support) * [Open Source Security & SBOM](#sca-and-sbom-support) * [API BOM](#api-bom-support) * [Infrastructure](#infrastructure-as-code-support) ## Code Security Support OX supports static code analysis for the following programming languages. | Language | Code Scanning | AI Fix Support | | --------------------------- | ------------- | -------------- | | **Python** | Yes | Yes | | **JavaScript / TypeScript** | Yes | Yes | | **Java** | Yes | Yes | | **C#** | Yes | Yes | | **PHP** | Yes | No | | **Swift** | Yes | No | | **Go** | Yes | No | | **Rust** | Yes | No | | **Dart** | Yes | No | | **Ruby** | Yes | No | | **C / C++** | Yes | No | | **Scala** | Yes | No | | **Kotlin** | Yes | No | | **COBOL** | Yes | No | | **Visual Basic .NET** | Yes | No | | **Clojure** | Yes | No | | **R** | Yes | No | | **Apex** | Yes | No | ## SCA & SBOM Support OX supports Software Composition Analysis (SCA) and Software Bill of Materials (SBOM) generation for the following package manager files. | Language | Package manager | License scanning | Vulnerability scan | Dependency graph | Reachability analysis | Pull request fix | | ------------------- | --------------- | ---------------- | ------------------ | ---------------- | --------------------- | ---------------- | | JavaScript | `npm` | Yes | Yes | Yes | Yes | Yes | | | `yarn` | Yes | Yes | Yes | Yes | Yes | | | `pnpm` | Yes | Yes | Yes | Yes | Yes | | | `bun` | Yes | Yes | Yes | Yes | No | | Python | `pip` | Yes | Yes | Yes | Yes | Yes | | | `Poetry` | Yes | Yes | Yes | Yes | Yes | | | `Pipenv` | Yes | Yes | Yes | Yes | Yes | | | `uv` | Yes | Yes | Yes | Yes | Yes | | | `PDM` | Yes | Yes | Yes | Yes | No | | Java | `Maven` | Yes | Yes | Yes | Yes | Yes | | | `Gradle` | Yes | Yes | Yes | Yes | Yes | | Scala | `SBT` | Yes | Yes | Yes | Yes | No | | | `Maven` | Yes | Yes | Yes | Yes | Yes | | | `Gradle` | Yes | Yes | Yes | Yes | Yes | | Kotlin | `Maven` | Yes | Yes | Yes | Yes | Yes | | | `Gradle` | Yes | Yes | Yes | Yes | Yes | | Objective-C / Swift | `CocoaPods` | Yes | Yes | Yes | Yes | No | | | `SwiftPM` | Yes | Yes | Yes | Yes | Yes | | | `XcodeGen` | Yes | Yes | Yes | Yes | Yes | | Go | `Go Modules` | Yes | Yes | Yes | Yes | Yes | | Dart | `Dart` | Yes | Yes | Yes | Yes | No | | Rust | `Rust` | Yes | Yes | Yes | Yes | No | | Ruby | `RubyGems` | Yes | Yes | Yes | Yes | No | | C# | `NuGet` | Yes | Yes | Yes | Yes | Yes | | Visual Basic .NET | `NuGet` | Yes | Yes | Yes | Yes | No | | PHP | `Composer` | No | Yes | Yes | Yes | Yes | | C/C++ | `Conan`¹ | Yes | Yes | Yes | Yes | Yes | > **Note ¹:** Conan dependencies are automatically detected in repositories using `conanfile.txt`, `conanfile.py`, `conan.lock`, `Makefile`, or `build.sh`. Supports Conan v1 and v2 lock file formats. ## API BOM Support OX supports API analysis and detection for specific specifications and frameworks. | Language | Web framework | API detection | API/Issue correlation¹ | | ------------------------------ | ------------------------------------ | :-----------: | :--------------------: | | **OpenAPI specification file** | – | Yes | – | | **Python** | Flask | Yes | Yes | | | FastAPI | Yes | Yes | | | Django | Yes | Yes | | | Connexion | Yes | Yes | | | Graphene | Yes | Yes | | | Tornado | Yes | Yes | | | Aiohttp | Yes | Yes | | | Sanic | Yes | Yes | | | Falcon | Yes | Yes | | **JavaScript & TypeScript** | Express.js | Yes | Yes | | | NestJS | Yes | Yes | | | Koa | Yes | Yes | | | Apollo GraphQL | Yes | Yes | | | Fastify | Yes | Yes | | | Hapi | Yes | Yes | | **Go** | Gin | Yes | Yes | | | Echo | Yes | Yes | | | Chi | Yes | Yes | | | Fiber | Yes | Yes | | | Gorilla Mux | Yes | Yes | | | gqlgen | Yes | Yes | | | graphql-go | Yes | Yes | | **Java** | Spring Boot | Yes | Yes | | | JAX-RS (Quarkus, Jersey, Dropwizard) | Yes | Yes | | | Micronaut | Yes | Yes | | **Kotlin** | Spring Boot | Yes | Yes | | | Ktor | Yes | Yes | | **Scala** | Spring Boot | Yes | Yes | | | Play | Yes | Yes | | **C#** | Microsoft ASP.NET Core MVC | Yes | Yes | | | ASP.NET Core Minimal APIs | Yes | Yes | | **Ruby** | Sinatra | Yes | Yes | | | Rails | Yes | Yes | | | Grape | Yes | Yes | | **PHP** | Slim | Yes | Yes | | | Laravel | Yes | Yes | | **Rust** | Axum | Yes | Yes | | | Actix Web | Yes | Yes | | **Elixir** | Phoenix | Yes | Yes | ## Infrastructure as Code Support OX detects and supports IaC tools and deployment configurations for the following platforms. | Tool | Supported Deployments | | --------------------- | ------------------------------------------- | | Terraform, Terragrunt | Alibaba, AWS, GCP, Azure, Yandex, OpenStack | | Helm Chart | Kubernetes | | Argo Workflows | Kubernetes | | Bicep | Azure | | CloudFormation | AWS | | Dockerfile | Any | | Kubernetes | Any | # Supported Connectors Open the accordions to view the list of connectors in each category. ## Infrastructure
CI/CD * Azure Pipelines * CircleCI * Drone CI * GitHub Actions * GitLab CI/CD * Jenkins * TeamCity * Travis CI * OX CI/CD Posture
Cloud Deployment * AWS * Azure * GCP
Git Posture * OX Git Posture
Kubernetes * AKS * EKS * GKE
Registry * Amazon ECR * Azure Container Registry * Docker Hub * GitLab Container Registry * Google Artifact Registry * Harbor * JFrog Artifactory * Nexus Container Registry * Red Hat Quay
Source Control * AWS CodeCommit * Azure Repos * Azure TFS * BitBucket Cloud * Bitbucket Data Center/Server * Gerrit Code Review * GitHub * GitLab
## Security
Cloud Context * Microsoft Defender for Cloud * Oligo * Orca * OX Cloud Context * PAN: Prisma Cloud - CSPM * Qualys * SentinelOne * Sysdig * Tenable * Upwind * Wiz
Code Security * Checkmarx SAST * Coverity * Coverity on Polaris * Fortify On Demand * Fortify Software Security Center * GitHub SAST * GitLab SAST * HCL AppScan * Klocwork * OX Code Security * Semgrep CLI * Semgrep Enterprise * Snyk * SonarQube * SonarCloud * Veracode
Container Security * JFrog Xray * OX Container Security * PAN: Prisma Cloud Containers * Snyk * Sysdig
Dynamic App Security * Applause * Bitsight * Bright Security * CyCognito * HCL AppScan * Invicti
Infrastructure as Code Scan * HCL AppSan * OX IaC Scan * Snyk
Open Source Security * Black Duck * Checkmarx SCA * Coverity on Polaris * Fortify on Demand * Fossa * GitHub Dependabot * GitLab Dependency Scanning * HCL AppScan * OX Open Source Security * Semgrep Enterprise * Snyk * Sonatype Nexus IQ CLI * Sonatype * Veracode * WhiteSource
SBOM * Fossa * OX SBOM Scan
Secret/PII Scan * Fortify on Demand * Fortify Software Security Center * GitGuardian * GitHub Secret Detection * GitLab Secret Detection * HCL AppScan * OX Secret/PII Scan * Semgrep Enterprise
Security Logs * [Logz.io](http://logz.io/) * Splunk
## Productivity
AI AppSec Advisor * ChatGPT
Dev Alerts * Microsoft Teams * Slack
Ticker Manager * Asana * Azure Boards * GitHub Issues * Jira * Monday * ServiceNow
# Contact us We're here to help! If you have any questions or have issues with OX Security, don't hesitate to contact our support team at . We'll get back to you as soon as possible to help you resolve any issues or answer any questions you may have. Thank you for choosing OX Security! We're excited to help you streamline your workflow and achieve your goals more efficiently. # Onboarding to OX The Onboarding to OX section guides you through the first steps of setting up OX for your organization.\ By the end of this section, you will have a connected, scanning, and visible environment that reflects your real development ecosystem.\ Once your setup is complete, you can continue to plan your next steps. OX connects to your existing development and deployment tools to provide complete visibility and continuous security governance.\ The onboarding process begins with environment setup and system connections, followed by your first scans and policy configuration. The onboarding process includes the following steps: 1. Review prerequisites 2. Connect to OX 3. Connect source control 4. Run the first scan 5. Review the results # Prerequisites and Access Before you begin setting up OX, review the following prerequisites to ensure a smooth onboarding process. ## Preparation steps 1. Review the [supported languages and frameworks](/supported-languages-and-frameworks). 2. Choose your hosting type: SaaS or On-Prem. In case of the on-prem installation, use the [On-Prem Preparation Guide](/get-started/onboarding-to-ox/prerequisites-and-access/on-prem-preparation-guide). ## Access and permissions 1. Ensure you have access to your company’s source control, CI/CD, registry, and ticketing systems. 2. Have credentials for your identity provider (for example, Okta, Azure AD, or Google Workspace) if you plan to enable SSO. #### External IP addresses If your organization restricts outbound or inbound network traffic by IP address, allow the following OX Security external IP addresses: | IP address | | ------------------- | | `54.76.158.3/32` | | `63.33.229.6/32` | | `34.249.173.69/32` | | `108.128.213.11/32` | > **Important:**\ > If your firewall, proxy, VPN, or network security controls use IP allowlists, add all of the preceding IP addresses to ensure uninterrupted connectivity with OX services. #### Agentic Pentester IP addresses If you use Agentic Pentester, allowlist the following IP addresses to enable OX to access and test your targets: * `63.33.147.64/32` * `18.202.47.201/32` ## Next Step After completing these checks, proceed to [Connecting to OX](/get-started/onboarding-to-ox/connect-to-ox). # On-Prem Preparation Guide The OX Platform Readiness Validator checks whether your on-premises server environment is ready for an OX Security deployment. The tool verifies infrastructure compatibility, validates network settings, and confirms access to required external services. It also generates the configuration file used during installation and creates log files to help with troubleshooting. On-prem (self-hosted) deployments run in environments that you manage, either in your own data centers or in your cloud accounts. Before installation, you receive a system requirements list. Use the validator to confirm that your environment meets these requirements. The validator helps you: * Confirm the environment early with your team and OX engineers * Reduce time spent in live troubleshooting * Prevent deployment delays * Ensure the system is ready before installation or updates > IMPORTANT: To ensure everything is ready before the installation or update, you must run this tool before the on-prem setup process. **The script does not install or update the platform; it only verifies readiness**. ## System requirements This section lists the hardware and software requirements required for validation and deployment. **Software requirements**
RequirementValue
Validator Version2.0.0
Required PrivilegesRoot (sudo) access
Supported OSUbuntu 22.04 LTS, Ubuntu 24.04 LTS
**Minimum hardware requirements**
ComponentRequirementPurpose
CPU Cores32+High-performance Kubernetes workload processing
Memory64+ GB RAMContainer orchestration and application memory
Storage512+ GB disk spaceContainer images, logs, and persistent data
NetworkStatic IP addressStable cluster communication
**Software tools**
Tool / ItemPurpose
curlDownloading components and testing connectivity
netstatChecking port availability
nslookupValidating DNS resolution
ipVerifying network interfaces
lsb_releaseDetecting OS version
## Validation script This section describes how the script manages access, data handling, and output to maintain a secure validation process. **Script functionality** * The script requires root (sudo) access to perform system-level validations. * It performs read-only checks and does not modify the system state. * All output files, including logs and configuration files, are saved locally on the server. * No sensitive data is transmitted externally at any stage. When you enter the command listed below, it downloads the script, creates an executable, and then runs the executable automatically using root privileges. At various points you’ll need to enter the configuration parameters listed in the table. **To run the validator command on the on-prem server:** 1. Make sure the server has: * Internet access to reach the S3 location * `curl` installed * Permission to run commands with `sudo` 2. Enter the following command in the terminal of the on-prem server to download and start the validator script. curl -o script.sh && chmod +x script.sh && sudo ./script.sh 3. During execution, the script prompts you to enter configuration parameters.
ParameterPromptFormat / OptionsPurposeValidation / Default
Host IP Address"Host IP Address"xxx.xxx.xxx.xxx (e.g., 192.168.1.100)Static IP address for accessing the OX PlatformMust be a valid IPv4 and exist on the system
Host Name"Host Name"Alphanumeric + hyphens (e.g., ox-platform-server)System hostname for the OX Platform serverMust follow standard hostname conventions
Server FQDN"Server FQDN (e.g., k8s-master.company.com)"hostname.domain.com (e.g., ox.company.com)Full domain name for accessing the platformMust be a valid FQDN with at least one dot
Use Proxy"Use proxy server? (y/n)"y/yes or n/noDetermine if a proxy is needed for internet accessDefault: n (no proxy)
Proxy URL"Proxy URL (http://proxy.example.com:8080)"http://hostname:port or https://hostname:portProxy server for outbound connections (if selected)Valid URL format if proxy is used
## Validation phases The validation process includes several phases, each validating different items. ### **1. System information display** | Checks | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

Shows current system specifications, including:

Operating System version

CPU core count

Total memory (GB)

Root disk space (GB)

Assessment timestamp

| ### **2. Prerequisite validation**
ChecksPossible Issues
Root/sudo privileges
Ubuntu OS detection
Required system commands availability

Running without sudo/root access

Missing system tools

Unsupported operating system

### **3. System requirements validation** | Checks | | -------------------------------------- | | CPU cores ≥ 32 | |


Memory ≥ 64 GB

| |


Disk space ≥ 512 GB

| |


OS version (22.04 or 24.04)

| ### **4. Network configuration validation** | Checks | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

Host IP exists on system interfaces

Hostname validation

DNS resolution for FQDN

Reverse DNS lookup

Network CIDR conflict detection

Kubernetes network planning

Network CIDRs Used:

Pod CIDR: 10.244.0.0/16 – Internal pod communication

Service CIDR: 10.96.0.0/12 – Kubernetes service networking

| ### **5. Proxy configuration validation** | Checks when a proxy is enabled | | -------------------------------------------------------------------------------------------------------------------------------------------------------- | |

Proxy URL format validation

HTTP connectivity through proxy

HTTPS connectivity through proxy

Ubuntu repository access via proxy

| ### **6. Package repository validation** | Checks | | ----------------------------------------------------------------------------------------------------------------------------------------------- | |

Ubuntu repository connectivity

APT package manager functionality

Security repository access

Package query capabilities

| ### **7. External URL accessibility validation** | Checks | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The validator verifies that the server can access all external services necessary for container images, package managers, Helm charts, and third-party integrations. | #### **Container registries** | Domain | Purpose | | ------------------- | ---------------------- | | `us-docker.pkg.dev` | OX Security containers | | `hub.docker.com` | Common containers | #### **Package registries** | Domain | Purpose | | -------------------- | ------------------- | | `registry.npmjs.org` | JavaScript packages | | `pypi.org` | Python packages | | `repo1.maven.org` | Java packages | | `rubygems.org` | Ruby packages | | `api.nuget.org` | C# packages | | `cdn.cocoapods.org` | iOS packages | | `conan.io` | C++ packages | #### **Helm Chart repositories** | Domain | Purpose | | -------------------- | -------------- | | `github.io` | Helm charts | | `charts.bitnami.com` | Bitnami charts | | `rook.io` | Storage charts | #### **External services** | Domain | Purpose | | ------------------ | ------------------------- | | `auth0.com` | Authentication services | | `cloud.google.com` | Google Cloud Platform | | `deps.dev` | Dependency analysis | | `datadoghq.com` | Logging and observability | ### **8. Platform readiness validation** | Checks | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

Swap disabled (required for Kubernetes)

Port availability (80, 443, 8080, 9090)

Directory write permissions

OX Platform directory structure

| #### Output files | File | Purpose | | ------------------------------ | ----------------------------------------------- | | `setup/config.toml` | Validated config for installation | | `ox_readiness_.log` | Full validation log for support/troubleshooting | #### Network planning | CIDR | Used For | | --------------- | -------------------------- | | `10.244.0.0/16` | Pod network | | `10.96.0.0/12` | Kubernetes service network | #### **Required open ports** | Port | Purpose | | ---- | -------------------- | | 80 | HTTP access | | 443 | HTTPS access | | 8080 | Management interface | | 9090 | Monitoring service | ## Result indicators
SymbolMeaning
✅All checks passed
⚠️Warnings (non-blocking issues)
❌Errors that must be fixed
## Common warnings, errors and recommended actions The table lists some common warnings, errors and recommended actions.
Warning / ErrorMeaningAction required
⚠️Hostname mismatchInput doesn’t match system hostnameWill be corrected during install
⚠️ Reverse DNS missingNo PTR record for IPAdd reverse DNS (optional)
⚠️ Port in usePort needed by OX is occupiedStop the conflicting service
⚠️ Swap enabledSwap memory is activeDisable swap before install
⚠️ Partial internet accessSome repos unreachableCheck firewall/proxy settings
❌ CPU cores insufficientLess than 32 coresUpgrade server hardware
❌ Memory insufficientLess than 64 GB RAMAdd RAM
❌ Disk space too smallLess than 512 GBResize or expand disk
❌ FQDN not resolvingDNS issueCreate or correct DNS record
❌ Repository access failedProxy/firewall blockingAdjust proxy/firewall settings
❌ Required port unavailableIn use by another serviceFree the port
## Troubleshooting If you experience issues during validation: 1. Review the log file for detailed information on any failed checks or errors. 2. Verify that your system meets all listed requirements. 3. If the issue persists, contact OX Security support and include the log file for assistance. The table lists some possible issues.
IssuePurposeCommand(s)
Script Won’t DownloadCheck internet connectivity. Download the validator script.ping google.com wget http://ox-infra-validator.s3-website-eu-west-1.amazonaws.com/ -O script.sh
Permission DeniedRun the script with root privileges. Add execute permission to the script.sudo ./script.sh chmod +x script.sh
DNS FailuresCheck the DNS configuration Test DNS resolution.cat /etc/resolv.conf nslookup your-fqdn.com
Proxy TestingVerify proxy connectivity.curl -x http://proxy:port http://google.com
APT Repository IssuesRefresh package lists. Review repository configuration Test repository reachabilitysudo apt update cat /etc/apt/sources.list curl -I http://archive.ubuntu.com/ubuntu/
## After validation Once the validator completes: 1. Open the generated `setup/config.toml` file to review the validated system and network configuration. 2. Save the log file (`ox_readiness_.log`) for future reference or troubleshooting if needed. 3. Once the validation is complete, contact your OX Security support to assist with the installation and deployment. # OX Broker OX Broker is a lightweight service deployed in your environment that enables OX Security to securely access and scan your internal resources without requiring any inbound firewall rules or network exposure. Rather than opening ports to OX Security, OX Broker Client initiates a single outbound HTTPS connection from your environment to the OX Broker Server. OX Security then routes all requests through that established connection, ensuring that your internal resources remain fully isolated from the public internet while still being accessible to the OX platform. ## Architecture ```mermaid flowchart LR subgraph ox ["OX Security (Cloud)"] platform["OX Security Platform"] server["OX Broker Server"] platform -->|"sends request"| server end subgraph customer ["Customer Environment"] broker["OX Broker Client"] connectors[("Internal Connectors\nGitHub · GitLab · Bitbucket\nArtifactory · Harbor · Jira")] end broker -->|"① outbound HTTPS"| server server -.->|"② using reverse tunnel"| broker broker -->|"③ authenticated request"| connectors ``` 1. The OX Broker Client initiates an outbound-only HTTPS connection to the OX Broker Server; no inbound firewall rules are required. 2. OX Security Platform routes requests back through the reverse tunnel to the OX Broker Client. 3. OX Broker Client forwards the authenticated request to the target internal connector. ## Supported Connectors * GitLab * GitHub * Azure TFS * Azure Boards * Harbor * GitLab Container Registry * JFrog Artifactory * Bitbucket Data Center or Server * Jira * Nexus Container Registry * Azure Container Registry ## Prerequisites Before you begin, contact an OX Security Customer Success representative for feature enablement and the OX Broker server dedicated address. OX Broker can be installed using **Docker Compose** on a Linux host or using a **Helm chart** on a Kubernetes cluster. Ensure your environment meets the following requirements based on your chosen method. ### General requirements
Requirement TypeDetails
Operating SystemUbuntu 22.04 or later, RHEL 9 or later
HardwareMinimum: 4 GB RAM, 2 CPU cores, 10 GB of available disk space
Network Requirements
  • Connectivity to your internal connectors from the host/node.
  • Outgoing traffic on port 443 to the address provided by OX.
  • Outgoing traffic to Docker Hub for pulling container images.
  • Share the public IP address of the host/node with OX.

Proxy: If your traffic is routed through a proxy, ensure port 443 HTTPS is allowed for outbound communication to the OX environment. Share the proxy IP address with OX Security.

### Docker Compose requirements | Requirement Type | Details | | ---------------- | ----------------------------------- | | Software | Docker Engine and Docker Compose V2 | | Access | Root access or sudo available | To verify your machine is configured correctly, download and run the readiness script: ```bash curl -fsSL https://installer.broker.ox.security/universal/oxbroker_readiness.sh -o oxbroker_readiness.sh chmod +x oxbroker_readiness.sh sudo ./oxbroker_readiness.sh ``` ### Helm requirements | Requirement Type | Details | | ---------------- | ------------------------------------------------------------------ | | Kubernetes | Access to a Kubernetes cluster | | Software | Helm version 3 or later, kubectl configured for the target cluster | ## Installing OX Broker Choose the method that matches your deployment environment and follow the relevant installation procedure: * [Docker Compose on a Linux host or virtual machine](#install-ox-broker-using-docker-compose) * [Helm chart on a Kubernetes cluster](#install-ox-broker-using-helm) ### Install OX Broker Using Docker Compose **To install OX Broker using Docker Compose:** 1. Download the installation script. ```bash curl -fsSL https://installer.broker.ox.security/universal/oxbroker_installer_universal.sh -o oxbroker_install.sh chmod +x oxbroker_install.sh ``` 2. Run the script as root, providing the OX Broker server address supplied by OX Security: * ```bash sudo ./oxbroker_install.sh --host ``` Or, if your environment routes traffic through a corporate proxy, add the `--proxy` flag. * 
sudo ./oxbroker_install.sh --host <BROKER_HOST> --proxy <PROXY_HOST>:<PROXY_PORT>
> **Note:**\ > `` must be the FQDN only, for example, `proxy.company.com`.\ > Do not include the protocol or port. The script generates an SSH key pair and credentials, and displays them on screen. 3. Send the public key to OX Security support and save the credentials in a safe location. 4. Once OX Security confirms the key has been registered, press `p` to proceed. The script starts the OX Broker services automatically. ### Install OX Broker Using Helm This installation method deploys OX Broker into a Kubernetes cluster using a Helm chart. **To install OX Broker using Helm:** 1. Add the OX Security Helm repository and update it. ```bash helm repo add ox https://charts.cloud.ox.security helm repo update ``` 2. Verify the chart is available. ```bash helm search repo ox/oxbroker ``` 3. Generate authentication keys locally. ```bash ssh-keygen -q -t rsa -b 4096 -f oxbroker-key -N "" -C "oxbroker@k8s" && cat oxbroker-key.pub ``` 4. Send the public key (`oxbroker-key.pub`) to OX Security and wait for confirmation that the key has been registered. 5. Create a Kubernetes namespace and secret containing the authentication keys. ```bash kubectl create namespace oxbroker kubectl create secret generic oxbroker-auth-key -n oxbroker \ --from-file=auth-privatekey=oxbroker-key \ --from-file=auth-publickey=oxbroker-key.pub ``` 6. Install the Helm chart using the broker server address provided by OX Security. ```bash helm install oxbroker ox/oxbroker -n oxbroker \ --set oxbroker.remoteHost= ``` 7. To configure proxy settings, add the following: ```bash --set proxy.enabled=true \ --set proxy.host= \ --set proxy.port= ``` > **Note:**\ > `` must be the FQDN only, for example, `proxy.company.com`.\ > Do not include the protocol or port. ## Verifying OX Broker **To confirm that OX Broker is running:** * For Docker Compose installations: ```bash cd oxbroker docker compose ps docker compose logs -f ``` * For Helm installations: ```bash kubectl get pods -n oxbroker kubectl logs -n oxbroker -l app=oxbroker --all-containers=true -f ``` ## Configuring OX Broker After installation completes, use with either method: 1. Log in to the OX Security portal. 2. Go to the relevant connector. 3. Enable **OX** **Broker**. Provide the following details: | Field | Details | | --------------------------------------------- | --------------------------------------------------------------------------------------------------- | | **Internal resource URL** | Provide the connector URL | | **Token** | Add your connector token | | **User** | The user that was generated during the OX Broker installation. | | **Password** | The password that was generated during the OX Broker installation. | | **Bypass SSL Verification (not recommended)** | Enable this option if your environment lacks a proper certificate or uses a self-signed certificate | ## Upgrading OX Broker **To upgrade OX Broker using Docker Compose:** 1. Navigate to the OX Broker directory. ```bash cd oxbroker ``` 2. Pull the latest stable images from Docker Hub. ```bash docker compose pull ``` 3. Restart the services with the updated images. ```bash docker compose up -d ``` 4. Verify the services are running. ```bash docker compose ps ``` **To upgrade OX Broker using Helm:** 1. Update the OX Security Helm repository. ```bash helm repo update ox ``` 2. Upgrade the deployment. ```bash helm upgrade oxbroker ox/oxbroker -n oxbroker ``` 3. To upgrade to a specific version. ```bash helm upgrade oxbroker ox/oxbroker -n oxbroker --version ``` 4. Verify the pods are running. ```bash kubectl get pods -n oxbroker ``` ## Uninstall OX Broker **Docker Compose** ```bash cd oxbroker docker compose down -v ``` **Helm** ```bash helm uninstall oxbroker -n oxbroker kubectl delete namespace oxbroker ``` # Connect to OX There are the following possibilities for getting connected to OX, depending on your role: * If you're the person setting up OX for your company, or if you are trying out OX on your own, first, set up your account and [create an organization](/get-started/onboarding-to-ox/connect-to-ox/create-an-organization). * If you have received an email inviting you to join an OX organization, you can set up your account by [accepting the invitation](/get-started/onboarding-to-ox/connect-to-ox/accept-an-invitation). * After your account is created, whether you created the organization yourself or joined an existing one, you can choose how you want to authenticate by reviewing the available options in [Sign in to OX](/get-started/onboarding-to-ox/connect-to-ox/sign-in-to-ox).
Create an organizationGet your company up and running with OX by creating an organization/pages/bsfQM652zyk5exau7Cxs/files/kNXlntmv907rBPENgCzl
Accept an invitationJoin an OX organization by accepting an invitation/pages/EhvfTiO3C0UqjQFbqYuE/files/A3pKt5KQpX9aEkAyjSfN
# Create an Organization Use this article to create your OX account and set up your organization.\ If you already received an invitation email, skip this article and see **Accept an invitation** instead. #### Create your OX account and organization **To create your account and organization:** 1. Go to [**https://app.ox.security/**](https://app.ox.security/) and click **Login**. 2. In the dialog, click **Sign up**. 3. Select how you want to create your account: * Google * GitHub * Email and password 1. Enter an email address. 2. Create a password that meets the requirements. 3. Verify your email using the link we send you. 4. OX creates your organization and prompts you to connect your repositories. * You can rename the organization now or later in **Settings**. 5. Choose how you want to get started: * **Load demo data** to explore OX without connecting your own repositories. * **Connect your repositories** to start scanning immediately. *** #### Load demo data **To load demo data:** 1. From the dialog, click **Alternatively try the OX Demo**. 2. OX loads and scans demo repositories and opens your **Dashboard**. *** #### Connect your repositories Follow the steps in the dialog to connect repositories from GitHub, GitLab, Bitbucket, or Azure Repos.\ If your source control system doesn’t appear in the dialog, close it and go to **Connectors** to select another platform. {% hint style="success" %} **At a glance:** Create an OX account and an organization, then explore how we can secure your software supply chain. You can use our demo data to get acquainted, or you can jump right in and connect your own repositories. {% endhint %} ## Overview {% hint style="info" %} If you've received an email invitation to join an OX organization, you can skip this article and create your account by accepting the invitation. {% endhint %} If you're trying out OX on your own or if you're the person setting up OX for your company, follow these steps to get connected: ### **1: Create your OX account and organization** **To create an OX account and organization:** 1. Go to [**https://app.ox.security/**](https://app.ox.security/) and click the **Login** button at the top-right corner of the screen. 2. In the dialog, click **Sign up.**\\
3. From the **Create your account** dialog, select the method you want to use to create your account: * Google (requires an existing Google account) * GitHub (requires an existing GitHub account) * **Note:** Choosing this option does not connect your GitHub repositories to OX. * Email address and password 1. Enter an email address where you can receive mail. 2. Create a password that meets the requirements displayed in the dialog. 3. Click **Continue.** 4. Check your email inbox for a verification email. Click the link in the email. 4. OX creates your organization and prompts you to connect a code repository. * If you want to change the organization name, you can do it here. Or you can change it later from the **Settings** page. 5. Follow the instructions in section 2a or 2b, below: * If you want to explore using the demo data before connecting your repositories, follow the steps in section [**2a**](#id-2a-load-demo-data)**.**\ \&#xNAN;**– OR –** * If you'd rather get started with OX using your own data, skip section 2a and follow the steps in section [**2b**](#id-2b-connect-your-repositories) to connect your repositories. ### 2a: Load demo data **To load the demo data:** 1. From the dialog, click the **Alternatively try the OX Demo** link.\\
2. OX loads and scans the demo data and opens the **Dashboard** (this takes a minute or two). {% hint style="success" %} Congratulations! You're ready to start exploring OX using the demo data. {% endhint %} ### 2b: Connect your repositories
{% hint style="warning" %} If your repositories are located on a source control platform other than the 4 available in this dialog: 1. Click **X** to close the dialog. 2. In the **Choose your environment setup** dialog that appears, click **Connect manually.** 3. The **Connectors** page will open, allowing you to select your source control platform from all the available OX-supported options. {% endhint %} **To connect your repositories, follow the instructions in the tab below for your source control platform:** {% tabs %} {% tab title="GitHub" %} There are 3 authorization options available for GitHub: * OX GitHub app (default) * GitHub identity provider * GitHub access token **To select an option and connect:** 1. Click the button.\ The **Connect** button and the **Other authorization options** dropdown are now available. 2. Select your authorization option: 1. To use the **OX GitHub app** (the default option), click **Connect** and follow the prompts. 2. To use the **GitHub identity provider:** * Click the arrow to open the **Other authorization options** dropdown. * Select **Use git identity provider** and follow the prompts to sign in and authorize OX. 3. To use a **GitHub access token:** * Click the arrow to open the **Other authorization options** dropdown. * Select **Use git access token.** * Enter the git host URL.\ **Note:** By default, OX enters the GitHub SaaS URL (). If you use a self-hosted git installation (GitHub Enterprise Server), replace it with your local git URL. * Follow the displayed instructions for generating a GitHub access token and paste it into the **Token** field. * Click **Connect.** 3. From the displayed list, select the repositories you want OX to monitor and protect. * By default, all detected repositories are selected. You can check/uncheck options according to your preference. * Check the **Monitor all newly created repos option** if you want OX to begin monitoring any future repos automatically upon their creation. 4. Click **Continue.** OX starts a scan of the selected repos and opens the **Dashboard.** {% hint style="success" %} Congratulations! You're ready to start using OX. **Note:** If you have repositories on other source control platforms, you can connect them anytime from the **Connectors** page. {% endhint %} {% endtab %} {% tab title="GitLab" %} There are 2 authorization options available for GitLab: * GitLab identity provider (default) * GitLab access token **To select an option and connect:** 1. Click the button.\ The **Connect** button and the **Other authorization options** dropdown are now available. 2. Select your authorization option: 1. To use the **GitLab identity provider** (the default option), click **Connect** and follow the prompts to sign in and authorize OX. 2. To use a **GitLab access token:** * Click the arrow to open the **Other authorization options** dropdown. * Select **Use git access token.** * Enter the git host URL.\ **Note:** By default, OX enters the GitLab SaaS URL (). If you use a self-hosted git installation (GitLab Self-Managed), replace it with your local git URL. * Follow the displayed instructions for generating a GitLab access token and paste it into the **Token** field. * Click **Connect.** 3. From the displayed list, select the repositories you want OX to monitor and protect. * By default, all detected repositories are selected. You can check/uncheck options according to your preference. * Check the **Monitor all newly created repos option** if you want OX to begin monitoring any future repos automatically upon their creation. 4. Click **Continue.** OX starts a scan of the selected repos and opens the **Dashboard.** {% hint style="success" %} Congratulations! You're ready to start using OX. **Note:** If you have repositories on other source control platforms, you can connect them anytime from the **Connectors** page. {% endhint %} {% endtab %} {% tab title="Bitbucket Cloud" %} There are 3 authorization options available for Bitbucket Cloud: * OX Bitbucket app (default) * Bitbucket identity provider **To select an option and connect:** 1. Click the button.\ The **Connect** button and the **Other authorization options** dropdown are now available. 2. Select your authorization option: 1. To use the **OX Bitbucket app** (the default option), click **Connect** and follow the prompts. 2. To use the **Bitbucket identity provider:** * Click the arrow to open the **Other authorization options** dropdown. * Select **Use git identity provider** and follow the prompts to sign in and authorize OX. 3. From the displayed list, select the repositories you want OX to monitor and protect. * By default, all detected repositories are selected. You can check/uncheck options according to your preference. * Check the **Monitor all newly created repos option** if you want OX to begin monitoring any future repos automatically upon their creation. 4. Click **Continue.** OX starts a scan of the selected repos and opens the **Dashboard.** {% hint style="success" %} Congratulations! You're ready to start using OX. **Note:** If you have repositories on other source control platforms, you can connect them anytime from the **Connectors** page. {% endhint %} {% endtab %} {% tab title="Azure Repos" %} There are 2 authorization options available for Azure Repos: * Azure identity provider (default) * Azure access token **To select an option and connect:** 1. Click the button.\ The **Connect** button and the **Other authorization options** dropdown are now available. 2. Select your authorization option: 1. To use the **Azure identity provider** (the default option), click **Connect** and follow the prompts to sign in and authorize OX. 2. To use an **Azure access token:** * Click the arrow to open the **Other authorization options** dropdown. * Select **Use git access token.** * The Azure SaaS URL () is automatically filled in. If you use an on-prem installation (Azure DevOps Server), do not connect from this screen. Instead, connect from the **Connectors** page. * Follow the displayed instructions for generating an Azure access token and paste it into the **Token** field. * Click **Connect.** 3. From the displayed list, select the repositories you want OX to monitor and protect. * By default, all detected repositories are selected. You can check/uncheck options according to your preference. * Check the **Monitor all newly created repos option** if you want OX to begin monitoring any future repos automatically upon their creation. 4. Click **Continue.** OX starts a scan of the selected repos and opens the **Dashboard.** {% hint style="success" %} Congratulations! You're ready to start using OX. **Note:** If you have repositories on other source control platforms, you can connect them anytime from the **Connectors** page. {% endhint %} {% endtab %} {% endtabs %} # Accept an Invitation Use this article to create your OX account after receiving an invitation to an existing organization. #### Accept an invitation and create your account **To accept an invitation:** 1. Open the invitation email and click **Accept invitation**. 2. In the dialog, select how you want to create your account. 3. Click **Continue**. OX logs you in and opens your organization's **Dashboard**. #### Notes Your available sign-in options depend on your organization’s IT policies.\ If your organization uses SSO, the dialog may look different or show fewer account-creation methods. {% hint style="success" %} **At a glance:** Create an OX account by accepting an invitation to join an organization. {% endhint %} Cool! You've received an email invitation to join an OX security organization. **To accept the invitation:** 1. Click the **Accept invitation** link in the email you received. 2. In the dialog, select one of the available options for creating your account.
3. Click **Continue,** and you're done! You'll be taken directly to your organization's [**Dashboard**](broken://pages/xhL81PmLKt3YjEeyu7lh), which is a great place to start exploring all of OX's features. {% hint style="warning" %} **Important!** Your organization's administrator and IT policies determine the options available for signing up and logging in. Therefore, the dialog you see may differ significantly from the one pictured above, especially if your organization uses single sign-on (SSO) with a service like Okta or SAML. {% endhint %} # Sign in to OX Use this article to choose the sign-in method for your organization. OX Security supports the following sign-in methods: * **Social/third-party sign-in using** [Google or GitHub](#allow-sign-in-with-google-or-github): Provides a strong layer of security by delegating password management via the OAuth/OpenID Connect protocol. Your application never stores the password. However, admins need to assign roles and scopes to users manually. * [Username and password](#allow-sign-in-with-username-and-password): Gives your organization complete control but imposes the highest administrative and security burden. The organization must secure and manage all user credentials and strictly enforce complex password standards. As with Google / GitHub, admins need to assign roles and scopes to users manually. * [Single Sign-On (SSO)](#allow-sign-in-using-single-sign-on-sso): Provides the highest level of security by centralizing credential management and policy enforcement (like Multi-Factor Authentication) through a dedicated Identity Provider (IdP). The initial setup is complex and requires time and specialized knowledge of IdP applications and protocols (SAML/OIDC). SSO provides the option for auto-provisioning, which the other methods do not. ### Prerequisites You need OX admin permissions. ### Allow sign-in with Google or GitHub Use this option when you want users to sign in to OX using existing Google or GitHub accounts. OX uses OAuth to authenticate with Google and GitHub. These providers do not return role or scope data. You assign each user’s role and scope in OX after the user signs in for the first time. **To allow sign-in with Google or GitHub:** 1. Go to **Settings > Login**. 2. Select **Google** or **GitHub**. 3. Confirm that the sign-in toggle is enabled. 4. After a user signs in, assign their role and scope. For instructions, see the article **Users**. ### Allow sign-in with username and password Use this option when you want users to authenticate directly with OX. Users set a password when they activate their account from the invitation email.\ You assign each user’s role and scope in OX after the user signs in for the first time. **To allow sign-in with username and password:** 1. Invite the user from the Users page. OX sends the invitation email. 2. The user activates the account and sets a password. 3. After a user signs in, assign their role and scope. For instructions, see the article **Users**. ### Allow sign-in using Single Sign-On (SSO) Use this option when your organization uses an identity provider (IdP) to manage authentication. SSO uses your IdP to verify users with corporate credentials.\ You can map IdP groups to OX roles and scopes to reduce manual work, or you can configure manually. **To set up SSO, follow the instructions in the relevant article:** * [SSO with Entra ID](/get-started/onboarding-to-ox/connect-to-ox/sign-in-to-ox/logging-into-microsoft-entra-id) * [SSO with Okta](/get-started/onboarding-to-ox/connect-to-ox/sign-in-to-ox/logging-into-okta) * [SSO with OpenID Connect](/get-started/onboarding-to-ox/connect-to-ox/sign-in-to-ox/sso-with-openid-connect) * [SSO with PingIdentity](/get-started/onboarding-to-ox/connect-to-ox/sign-in-to-ox/sso-with-saml-1) * [SSO with SAML](/get-started/onboarding-to-ox/connect-to-ox/sign-in-to-ox/sso-with-saml) # SSO with SAML OX Security supports Single Sign-On (SSO) for secure authentication and centralized access control.\ The connection allows users to sign in to OX Security with their corporate credentials managed by an Identity Provider (IdP). OX Security supports: * **Auto-provisioning:** Automatically creates user accounts at first login. * **App-initiated login:** Starts login directly from the OX sign-in page. * **Group-based roles and scopes:** Assigns OX permissions based on IdP groups. When auto-provisioning is **ON**: * OX automatically creates a user account when someone signs in through the IdP. * Account details (name, email, groups) come directly from the IdP. * You do not need to invite users manually. When auto-provisioning is **OFF:** * OX does not create accounts automatically. * You must invite users manually before they can access OX. {% hint style="info" %} * Users who are not invited using the OX Members page receive the **Read Only** role by default. You can change this setting and define any other role as default. See [Roles](/admin-settings/roles). * When auto-provisioning with roles is configured, role assignments must be managed in the IdP. * Roles assigned directly in OX are ignored for SSO users. {% endhint %} ## Prerequisites * OX and IdP admin permissions * A decision on enabling optional features: * App-initiated login * Auto-provisioning for roles * Auto-provisioning for scopes * Access to your IdP’s SAML metadata and X.509 certificate {% hint style="info" %} If you are new to SAML 2.0, check out the article [Connect Your App to SAML Identity Providers](https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/saml). {% endhint %} ## Process steps 1. [Get the OX inputs for your IdP \[OX\]](#step1) 2. [Register the application \[IdP\]](#step-2-register-the-application-in-the-idp-idp) 3. [Configure the IdP settings \[IdP\]](#step-3-configure-the-idp-settings-idp) 4. [Configure SSO \[OX\]](#step-4-configure-sso-ox) 5. [Enable IdP app-initiated login and visibility \[OX - IdP\]](#optional-step-5-enable-idp-app-initiated-login-and-visibility-ox-idp) 6. [Configure auto-provisioning for roles \[OX - IdP\]](#optional-step-6-configure-auto-provisioning-for-roles-ox-idp) 7. [Configure Auto-Provisioning for Scopes \[OX - IdP\]](#optional-step-7-configure-auto-provisioning-for-scopes-ox-idp) 8. [Test the sign-in \[OX\]](#step-8-test-the-sign-in-ox) 9. [Troubleshooting](#troubleshooting) ## Step 1: Get OX Inputs for your IdP \[OX] The inputs are specific for your IdP and organization. 1. To get the correct values from OX, go to **Settings > Login** and click the IdP icon. The [Configuration ](https://app.ox.security/settings?tab=login\&loginOption=SAML)dialog appears.
2. Click **SAML SSO SETUP INSTRUCTIONS**. 3. Locate the following parameters, copy the values, and save them for use in Step 3. * Single Sign-On URL (ACS) * Audience URI (SP Entity ID) * Initiate login URI ## Step 2: Register the application \[IdP] 1. Log in to your IdP Admin console. 2. Go to **Applications > Create App Integration** (or equivalent). 3. Select **SAML 2.0** as the sign-in method. 4. Enter an App integration name e.g., OX Security SSO. 5. Save the changes. ## Step 3: Configure the IdP settings \[IdP] 1. In your IdP, open the SAML setup or metadata page. 2. Paste the OX values that you saved in Step 1 into your IdP's configuration: * Single Sign-On URL (ACS) * Audience URI (SP Entity ID) * Initiate login URI 3. Set the attributes for: name, email, email\_verified. 4. Collect and save the following IdP details to paste into OX. * Company domain: Your IdP domain name. * Identity provider Single Sign-On URL: the IdP SSO endpoint. * X.509 certificate: Download and convert to Base64 and save the file. ## Step 4: Configure SSO \[OX] 1. In OX, go to **Settings > Login** and click the relevant IdP icon. The [Configuration ](https://app.ox.security/settings?tab=login\&loginOption=SAML)dialog appears.
2. Enter the details collected from your IdP in Step 3. * Company domain * Sign-In URL (Identity Provider Single Sign-On URL) * X.509 certificate (Base64) 3. Click **Save**. {% hint style="info" %} Auto-provisioning is enabled by default. The feature allows OX to create user accounts automatically upon first sign-in. To disable it, deactivate the toggle. {% endhint %} ## Optional Step 5: Enable IdP app-initiated login and visibility \[OX-IdP] This step allows users to start their login directly from your IdP dashboard. 1. In your IdP, open **General settings** for the OX SAML app. 2. Add the Initiate login URI you saved in Step 1. 3. Click **Save**. ## Optional Step 6: Configure auto-provisioning for roles \[OX-IdP] This step enables the automatic assignment of [OX Security roles](/admin-settings/roles) based on user groups in your IdP. There are the following types of roles: * Roles predefined by OX, * Custom roles. ### Create user groups for predefined roles Each predefined role group requires a prefix. The default is: OXApp-. You can change the default prefix to a custom one. **To change the default prefix:** 1. Go to **Settings > Login > \[IdP icon]** and enter a different prefix.
2. **Create IdP role groups:** In your IdP, go to **Directory > Groups** and create groups using these exact names (case-sensitive) for each OX role you want to sync: * OXApp-Admin * OXApp-Developer * OXApp-Dev Manager/Security Champion * OXApp-Policy Manager * OXApp-Read Only ### Create user groups for custom roles In case you have custom role(s) defined in OX, you need to create groups using the exact labels OX generates for your custom roles. The label is different from the custom role name. You can view the custom role label only in the instructions provided by OX within the Configuration dialog. **To locate the custom role label:** 1. Go to **Settings > Login > \[IdP icon]** and in the instruction box, select **+**. 2. Scroll down in the instructions box until you get to **Advanced settings (auto provisioning) - Setting roles**. 3. Read the procedure. The custom role label appears next to the custom role name in brackets. You cannot change it. 4. Use this label as the name of your new group in IdP. **For example:** I know that the admin defined a custom role called Executive Viewer. If I am looking for the label that OX generated for the custom role Executive Viewer, first I locate the custom role Executive Viewer in brackets and then I can see that OX generated a label for this custom role "OXApp-CustomRole1".
### **Complete the process** 1. **Map group attributes**: In your IdP, ensure you have groups attribute mapping enabled. 2. **Enable sync:** In OX, go to **Settings > Login > \[IdP icon]** and enable **Sync OX Group Roles** using the prefix you selected. 3. Select **Save**. 4. In the IdP, assign users who need that specific scope access as members of the corresponding group. ## Optional Step 7: Configure Auto-Provisioning for Scopes \[OX-IdP] This step enables the automatic assignment of granular access scopes based on user groups in your IdP. There is no prefix required for Scopes in OX; however, you do need to create a Scopes group and assign an owner. 1. In OX, go to the Applications page, and select an app from the list. From the header, click the **Assign Owner** icon.
2. In the **Assign Application Owners** screen: * Select a role. * App New Owner: Enter a descriptive name. * Email: Enter an email. The email can be a functional address.
3. Click + **ADD**. This generates the SSO Group String. Save this string to paste into the IdP.
4. **Create scope groups in the IdP.** In your IdP, create groups for the OX scopes that you want to assign.
For App owner and other UI-visible scopes Use the **SSO Group String** that you generated in OX in the previous steps as the IdP group name. Example: ``` OXAppOwnerScope-DevOps-id:devops@acme.com ```
For tag scopes Tag scopes are not displayed in the OX scope selector, so OX does not generate an **SSO Group String** for them. Instead, create the IdP group name by using the following format: ``` OXTagScope--id: ``` Example: ``` OXTagScope-app-id:acme-app ``` Replace: * `` with the tag name. * `` with the unique ID of the tag. The tag ID is not available in the OX user interface. To obtain it, use the OX API to retrieve the tag details, and then use the returned tag ID when constructing the group name. > **Note:** Tag IDs can currently be retrieved only through the OX API by using the **Get Single Tag** endpoint.
5. **Assign members in the IdP:** In the IdP, assign members to the relevant scope groups. 6. **Enable sync in OX:** In OX, go to **Settings > Login > \[Idp]** and enable the toggle **Sync OX Group Scopes**. Generally select the **Entire Organization.**
7. Click **Save**. ## Step 8: Test the Sign-In \[OX] 1. In OX, log out then log in again using your SSO. 2. Verify that the configured roles and scopes from your IdP are applied correctly. Your OX organization is now connected to your IdP. Users can sign in securely with corporate credentials, and applied roles and scopes are based on the IdP configuration. ## Troubleshooting The table lists some possible issues and recommended actions.
IssueCauseAction
User cannot sign inIncorrect SSO URL or certificate.Verify the IdP Single Sign-On URL and X.509 certificate match the OX setup.
Account not createdAuto-provisioning disabled.Enable auto-provisioning in your IdP or invite the user manually.
Role not appliedGroup mapping mismatch.Ensure IdP group names match OX role names exactly.
Scope not appliedScope group format incorrect.Confirm group naming matches OXAppOwnerScope- or OXTagScope- format.
Role changes ignored in OXRoles managed in IdP.Manage all role assignments within the IdP.
Certificate errorsExpired or malformed X.509.Re-upload a valid Base64 certificate in OX.
# SSO with PingIdentity OX Security supports Single Sign-On (SSO) for secure authentication and centralized access control.\ The connection allows users to sign in to OX Security with their corporate credentials managed by an Identity Provider (IdP). OX Security supports: * **Auto-provisioning:** Automatically creates user accounts at first login. * **App-initiated login:** Starts login directly from the OX sign-in page. * **Group-based roles and scopes:** Assigns OX permissions based on IdP groups. When auto-provisioning is **ON**: * OX automatically creates a user account when someone signs in through the IdP. * Account details (name, email, groups) come directly from the IdP. * You do not need to invite users manually. When auto-provisioning is **OFF:** * OX does not create accounts automatically. * You must invite users manually before they can access OX. {% hint style="info" %} * Users who are not invited using the OX Members page receive the **Read Only** role by default. You can change this setting and define any other role as default. See [Roles](/admin-settings/roles). * When auto-provisioning with roles is configured, role assignments must be managed in the IdP. * Roles assigned directly in OX are ignored for SSO users. {% endhint %} ## Prerequisites * OX and IdP admin permissions * Access to your PingIdentity SAML configuration details and X.509 certificate * A decision on enabling optional features: * App-initiated login * Auto-provisioning for roles * Auto-provisioning for scopes {% hint style="info" %} If you are new to PingIdentity, check out the article [Quickstart: Create a PingIdentity Application](https://docs.pingidentity.com/solution-guides/workforce_use_cases/htg_config_saml_app.html#configuring-a-saml-application-in-pingone). {% endhint %} ## Process steps 1. [Get the OX inputs for your IdP \[OX\]](#step1) 2. [Register the application \[IdP\]](#step-2-register-the-application-in-the-idp-idp) 3. [Configure the IdP settings \[IdP\]](#step-3-configure-the-idp-settings-idp) 4. [Configure SSO \[OX\]](#step-4-configure-sso-ox) 5. [Enable IdP app-initiated login and visibility \[OX - IdP\]](#optional-step-5-enable-idp-app-initiated-login-and-visibility-ox-idp) 6. [Configure auto-provisioning for roles \[OX - IdP\]](#optional-step-6-configure-auto-provisioning-for-roles-ox-idp) 7. [Configure Auto-Provisioning for Scopes \[OX - IdP\]](#optional-step-7-configure-auto-provisioning-for-scopes-ox-idp) 8. [Test the sign-in \[OX\]](#step-8-test-the-sign-in-ox) 9. [Troubleshooting](#troubleshooting) ## Step 1: Get OX Inputs for your IdP \[OX] The inputs are specific for your IdP and organization. 1. To get the correct values from OX, go to **Settings > Login** and click the IdP icon. The [Configuration ](https://app.ox.security/settings?tab=login\&loginOption=PingFederate)screen opens.
2. Click **PINGIDENTITY SSO SETUP INSTRUCTIONS**. 3. Locate the parameters, copy the values, and save them for use in Step 3. * Single Sign-On URL (ACS) * SP Entity ID * Initiate login URI ## Step 2: Register the application \[IdP] 1. Log in to your PingIdentity Admin Console. 2. Go to **Applications > Add Application**. 3. Select SAML 2.0 as the sign-in method. 4. Enter an application name, for example, OX Security SSO. 5. Save the changes. ## Step 3: Configure the IdP settings \[IdP] 1. In your PingIdentity console, under the application you created, go to the **Browser SSO/Connection** tab (or similar). 2. Paste the OX values from the [Configuration screen](https://app.ox.security/settings?tab=login\&loginOption=PingFederate) that you saved in Step 1 and paste them into your IdP's configuration: * Single Sign-On URL (ACS) * Audience URI (SP Entity ID) * Initiate Login URI (Target Resource URL in PingIdentity) 3. In **Attribute Mapping** (or Attribute Contract) set the attributes for: name, email, email\_verified. 4. Collect and save the following PingIdentity details to paste into OX later: * Initiate Single Sign-On URL: the IdP SSO endpoint * X.509 Certificate: download the signing certificate (PEM .crt file). It’s already Base64-encoded. ## Step 4: Configure SSO \[OX] 1. In OX, go to **Settings > Login** and click the relevant IdP icon. The [Configuration ](https://app.ox.security/settings?tab=login\&loginOption=SAML)screen opens. 2. Enter the details collected from your IdP in Step 3. * Initiate Single Sign-On URL * X.509 certificate (Base64) 3. Click **Save**.

Auto-provisioning is enabled by default. The feature allows OX to create user accounts automatically upon first sign-in. To disable it, deactivate the toggle.

## Optional Step 5: Enable IdP app-initiated login and visibility \[OX-IdP] This step allows users to start their login directly from your IdP dashboard. 1. In your IdP, open **General Settings** (or Connection Configuration) for the PingIdentity app 2. Add the Initiate login URI you saved in Step 1. 3. Click **Save**. ## Optional Step 6: Configure auto-provisioning for roles \[OX-IdP] This step enables the automatic assignment of [OX Security roles](/admin-settings/roles) based on user groups in your IdP. There are the following types of roles: * Roles predefined by OX, * Custom roles. ### Create user groups for predefined roles Each predefined role group requires a prefix. The default is: OXApp-. You can change the default prefix to a custom one. **To change the default prefix:** 1. Go to **Settings > Login > \[IdP icon]** and enter a different prefix.
2. **Create IdP role groups:** In your IdP, go to **Directory > Groups** and create groups using these exact names (case-sensitive) for each OX role you want to sync: * OXApp-Admin * OXApp-Developer * OXApp-Dev Manager/Security Champion * OXApp-Policy Manager * OXApp-Read Only ### Create user groups for custom roles In case you have custom role(s) defined in OX, you need to create groups using the exact labels OX generates for your custom roles. The label is different from the custom role name. You can view the custom role label only in the instructions provided by OX within the Configuration dialog. **To locate the custom role label:** 1. Go to **Settings > Login > \[IdP icon]** and in the instruction box, select **+**. 2. Scroll down in the instructions box until you get to **Advanced settings (auto provisioning) - Setting roles**. 3. Read the procedure. The custom role label appears next to the custom role name in brackets. You cannot change it. 4. Use this label as the name of your new group in IdP. **For example:** I know that the admin defined a custom role called Executive Viewer. If I am looking for the label that OX generated for the custom role Executive Viewer, first I locate the custom role Executive Viewer in brackets and then I can see that OX generated a label for this custom role "OXApp-CustomRole1".
### **Complete the process** 1. **Map group attributes**: In your IdP, ensure you have groups attribute mapping enabled. 2. **Enable sync:** In OX, go to **Settings > Login > \[IdP icon]** and enable **Sync OX Group Roles** using the prefix you selected. 3. Select **Save**. 4. In the IdP, assign users who need that specific scope access as members of the corresponding group. ## Optional Step 7: Configure Auto-Provisioning for Scopes \[OX-IdP] This step enables the automatic assignment of granular access scopes based on user groups in your IdP. There is no prefix required for Scopes in OX; however, you do need to create a Scopes group and assign an owner. 1. In OX, go to the Applications page, and select an app from the list. From the header, click the **Assign Owner** icon.
2. In the **Assign Application Owners** screen: * Select a role. * App New Owner: Enter a descriptive name. * Email: Enter an email. The email can be a functional address.
3. Click + **ADD**. This generates the SSO Group String. Save this string to paste into the IdP.
4. **Create scope groups in the IdP.** In your IdP, create groups for the OX scopes that you want to assign.
For App owner and other UI-visible scopes Use the **SSO Group String** that you generated in OX in the previous steps as the IdP group name. Example: ``` OXAppOwnerScope-DevOps-id:devops@acme.com ```
For tag scopes Tag scopes are not displayed in the OX scope selector, so OX does not generate an **SSO Group String** for them. Instead, create the IdP group name by using the following format: ``` OXTagScope--id: ``` Example: ``` OXTagScope-app-id:acme-app ``` Replace: * `` with the tag name. * `` with the unique ID of the tag. The tag ID is not available in the OX user interface. To obtain it, use the OX API to retrieve the tag details, and then use the returned tag ID when constructing the group name. > **Note:** Tag IDs can currently be retrieved only through the OX API by using the **Get Single Tag** endpoint.
5. **Assign members in the IdP:** In the IdP, assign members to the relevant scope groups. 6. **Enable sync in OX:** In OX, go to **Settings > Login > \[Idp]** and enable the toggle **Sync OX Group Scopes**. Generally select the **Entire Organization.**
7. Click **Save**. ## Step 8: Test the Sign-In \[OX] 1. In OX, log out and then log in again using your SSO. 2. Verify that the configured roles and scopes from your IdP are applied correctly. Your OX organization is now connected to your IdP. Users can sign in securely with corporate credentials, and applied roles and scopes are based on the IdP configuration. ## Troubleshooting The table lists some possible issues and recommended actions.
IssueRecommended Action
Users cannot sign inVerify that the PingIdentity Single Sign-On Service URL and X.509 certificate match the OX setup.
Account not createdEnable auto-provisioning in OX or invite the user manually.
Role not appliedEnsure PingIdentity group names match OX role names exactly.
Scope not appliedConfirm group naming follows OXAppOwnerScope- or OXTagScope- format.
Role changes ignored in OXManage all role assignments within PingIdentity.
Certificate errorsRe-upload a valid Base64-encoded certificate in OX.
# SSO with OpenID Connect OX Security supports Single Sign-On (SSO) for secure authentication and centralized access control.\ The connection allows users to sign in to OX Security with their corporate credentials managed by an Identity Provider (IdP). OX Security supports: * **Auto-provisioning:** Automatically creates user accounts at first login. * **App-initiated login:** Starts login directly from the OX sign-in page. * **Group-based roles and scopes:** Assigns OX permissions based on IdP groups. When auto-provisioning is **ON**: * OX automatically creates a user account when someone signs in through the IdP. * Account details (name, email, groups) come directly from the IdP. * You do not need to invite users manually. When auto-provisioning is **OFF:** * OX does not create accounts automatically. * You must invite users manually before they can access OX. {% hint style="info" %} * Users who are not invited using the OX Members page receive the **Read Only** role by default. You can change this setting and define any other role as default. See [Roles](/admin-settings/roles). * When auto-provisioning with roles is configured, role assignments must be managed in the IdP. * Roles assigned directly in OX are ignored for SSO users. {% endhint %} ## Prerequisites * OX and IdP admin permissions * A decision on enabling optional features: * App-initiated login * Auto-provisioning for roles * Auto-provisioning for scopes * Access to your IdP’s OIDC metadata and ability to create a Client ID and Client Secret {% hint style="info" %} If you are new to OIDC, check out the article [Connect to OpenID Connect Identity Providers](https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/oidcConnect%20Your%20App%20to%20SAML%20Identity%20Providers.) {% endhint %} ## Process steps 1. [Get the OX inputs for your IdP \[OX\]](#step1) 2. [Register the application \[IdP\]](#step-2-register-the-application-in-the-idp-idp) 3. [Configure the IdP settings \[IdP\]](#step-3-configure-the-idp-settings-idp) 4. [Configure SSO \[OX\]](#step-4-configure-sso-ox) 5. [Enable IdP app-initiated login and visibility \[OX - IdP\]](#optional-step-5-enable-idp-app-initiated-login-and-visibility-ox-idp) 6. [Configure auto-provisioning for roles \[OX - IdP\]](#optional-step-6-configure-auto-provisioning-for-roles-ox-idp) 7. [Configure Auto-Provisioning for Scopes \[OX - IdP\]](#optional-step-7-configure-auto-provisioning-for-scopes-ox-idp) 8. [Test the sign-in \[OX\]](#step-8-test-the-sign-in-ox) 9. [Troubleshooting](#troubleshooting) ## Step 1: Get OX Inputs for your IdP \[OX] The inputs are specific for your IdP and organization. 1. To get the correct values from OX, go to **Settings > Login** and click the IdP icon. The [Configuration ](https://app.ox.security/settings?tab=login\&loginOption=OIDC)screen opens.
1. Click **OIDC SSO SETUP INSTRUCTIONS**. 2. Find the parameters, copy the values, and save them for use in Step 3: * Redirect URI (Callback URL) * Initiate login URI ## Step 2: Register the application \[IdP] 1. Log in to your IdP Admin console. 2. Go to **Applications > Create App Integration** (or equivalent). 3. Select OIDC 2.0 as the sign-in method. 4. Choose Web Application as application type. 5. Set the Sign-in redirect URI to: 6. Save to generate the Client ID and Client Secret. ## Step 3: Configure the IdP settings \[IdP] 1. In your IdP, open the Admin console. 2. Configure the Redirect URI (Callback URL): Use the value you saved in Step 1. 3. Copy these values from your IdP and save them for use in Step 4. * OIDC Domain * Client ID * Client Secret ## Step 4: Configure SSO \[OX] 1. In OX, go to **Settings > Login** and click the relevant IdP icon. The [Configuration ](https://app.ox.security/settings?tab=login\&loginOption=OIDC)screen opens. 2. Enter the details collected from your IdP in Step 3. * OIDC Domain * Client ID * Client Secret 3. Click **Save**.

Auto-provisioning is enabled by default. The feature allows OX to create user accounts automatically upon first sign-in. To disable it, deactivate the toggle.

## Optional Step 5: Enable IdP app-initiated login and visibility \[OX-IdP] This step allows users to start their login directly from your IdP dashboard. 1. In your IdP, open **General settings** for the OIDC app. 2. Add the Initiate login URI you saved in Step 1. 3. Click **Save**. ## Optional Step 6: Configure auto-provisioning for roles \[OX-IdP] This step enables the automatic assignment of [OX Security roles](/admin-settings/roles) based on user groups in your IdP. There are the following types of roles: * Roles predefined by OX, * Custom roles. ### Create user groups for predefined roles Each predefined role group requires a prefix. The default is: OXApp-. You can change the default prefix to a custom one. **To change the default prefix:** 1. Go to **Settings > Login > \[IdP icon]** and enter a different prefix.
2. **Create IdP role groups:** In your IdP, go to **Directory > Groups** and create groups using these exact names (case-sensitive) for each OX role you want to sync: * OXApp-Admin * OXApp-Developer * OXApp-Dev Manager/Security Champion * OXApp-Policy Manager * OXApp-Read Only ### Create user groups for custom roles In case you have custom role(s) defined in OX, you need to create groups using the exact labels OX generates for your custom roles. The label is different from the custom role name. You can view the custom role label only in the instructions provided by OX within the Configuration dialog. **To locate the custom role label:** 1. Go to **Settings > Login > \[IdP icon]** and in the instruction box, select **+**. 2. Scroll down in the instructions box until you get to **Advanced settings (auto provisioning) - Setting roles**. 3. Read the procedure. The custom role label appears next to the custom role name in brackets. You cannot change it. 4. Use this label as the name of your new group in IdP. **For example:** I know that the admin defined a custom role called Executive Viewer. If I am looking for the label that OX generated for the custom role Executive Viewer, first I locate the custom role Executive Viewer in brackets and then I can see that OX generated a label for this custom role "OXApp-CustomRole1".
### **Complete the process** 1. **Map group attributes**: In your IdP, ensure you have groups attribute mapping enabled. 2. **Enable sync:** In OX, go to **Settings > Login > \[IdP icon]** and enable **Sync OX Group Roles** using the prefix you selected. 3. Select **Save**. 4. In the IdP, assign users who need that specific scope access as members of the corresponding group. ## Optional Step 7: Configure Auto-Provisioning for Scopes \[OX-IdP] This step enables the automatic assignment of granular access scopes based on user groups in your IdP. There is no prefix required for Scopes in OX; however, you do need to create a Scopes group and assign an owner. 1. In OX, go to the Applications page, and select an app from the list. From the header, click the **Assign Owner** icon.
2. In the **Assign Application Owners** screen: * Select a role. * App New Owner: Enter a descriptive name. * Email: Enter an email. The email can be a functional address.
3. Click + **ADD**. This generates the SSO Group String. Save this string to paste into the IdP.
4. **Assign members in the IdP:** In the IdP, assign members to the relevant scope groups.
For tag scopes Tag scopes are not displayed in the OX scope selector, so OX does not generate an **SSO Group String** for them. Instead, create the IdP group name by using the following format: ``` OXTagScope--id: ``` Example: ``` OXTagScope-app-id:acme-app ``` Replace: * `` with the tag name. * `` with the unique ID of the tag. The tag ID is not available in the OX user interface. To obtain it, use the OX API to retrieve the tag details, and then use the returned tag ID when constructing the group name. > **Note:** Tag IDs can currently be retrieved only through the OX API by using the **Get Single Tag** endpoint.
For App owner and other UI-visible scopes Use the **SSO Group String** that you generated in OX in the previous steps as the IdP group name. Example: ``` OXAppOwnerScope-DevOps-id:devops@acme.com ```
5. **Assign members in the IdP:** In the IdP, assign members to the relevant scope groups. 6. **Enable sync in OX:** In OX, go to **Settings > Login > \[Idp]** and enable the toggle **Sync OX Group Scopes**. Generally select the **Entire Organization.**
7. Click **Save**. ## Step 8: Test the Sign-In \[OX] 1. In OX, log out then log in again using your SSO. 2. Verify that the configured roles and scopes from your IdP are applied correctly. Your OX organization is now connected to your IdP. Users can sign in securely with corporate credentials, and applied roles and scopes are based on the IdP configuration. ## Troubleshooting The table lists some possible issues and recommended actions.
IssueCauseAction
invalid_tokenClient Secret mismatchRegenerate the Client Secret in the IdP.
invalid_redirect_uriCallback URL not registeredRegister the URL from the production environment.
Missing user infoClaims not enabledAdd profile and email scopes in the IdP; enable name, email, email_verified.
Roles not appliedGroups claim missing or filter not setEnable the groups claim. Set the group claim filter to match all (.*) if required.
Scopes not appliedScope group name format is wrongVerify that OXAppOwnerScope-… or OXTagScope-… formats exactly.
# SSO with Okta Okta is an identity and access management platform that supports OpenID Connect (OIDC) for secure single sign-on. OX supports OIDC SSO with Okta so your users can sign in to OX with their company credentials. This guide shows how to create an OIDC Web Application in Okta, connect it to OX, and optionally use Okta groups to control OX roles and scopes. ## Prerequisites * Okta Admin Console permissions to create applications and manage groups. * OX Owner or Admin permissions. ## Step 1: Create the OIDC application \[Okta] Create an OpenID Connect (OIDC) Web Application in Okta that represents OX. This app sets the redirect URI and provides the Client ID and Client Secret you need when connecting to OX. **To create the OIDC application:** 1. Sign in to the **Okta Admin Console**. 2. Select **Applications** > **Applications** > **Create App Integration**, and set the following: * **Sign-in method:** **OIDC – OpenID Connect**. * **Application type:** **Web Application**. 3. Select **Next**, and set the following: * **App integration name:** enter a clear name, for example, **OX Security SSO**. * **Sign-in redirect URIs:** add your OX callback URL. Take the URL from the [Okta Configuration ](https://app.ox.security/settings?tab=login\&loginOption=Okta)dialog box (). 4. Select **Save**. ## Step 2: Get Client ID and Client Secret \[Okta] * In the **Okta Admin Console**, go to **Applications > Applications > your app >** **General**, and find and copy: **Client ID** and **Client Secret**. ## Step 3: Configure SSO in OX \[OX] 1. In the OX platform, go to **Settings** > **Login Settings** and select **Okta**. The [Okta Configuration](https://app.ox.security/settings?tab=login\&loginOption=Okta) dialog box opens.
ParameterDescription
Okta DomainAdd your Okta domain (for example, https://your-domain.okta.com).
Client IDPaste the Client ID from the Okta app.
Client SecretPaste the Client Secret from the Okta app.
Enable auto provisioningEnable this option if you want users to sign in without inviting them in the OX Members page and to control roles and scopes using Okta groups.
Note:
- If you do not configure auto-provisioning with roles, users who are not invited from the OX Members page sign in as Read Only by default.
- If you configure auto-provisioning with roles, manage role assignments only in Okta. Role changes in the OX Members page are ignored for users who sign in with Okta SSO.
Sync OX Group RolesRoles define the permission level a user has in OX (Admin, Developer, Policy Manager, Read Only). When you map Okta groups to OX roles, Okta becomes the single source of truth for who can do what. This reduces manual changes in OX, enforces least-privilege, and keeps audits simple because access is managed in one place.
Sync OX Group ScopesScopes control what data and assets a user can see or manage in OX (for example by application owner or by tag). Mapping Okta groups to OX scopes lets you segment access cleanly across teams, business units, or projects. You keep sensitive areas visible only to the right people, and visibility updates follow org changes in Okta automatically.
2. Select **Save**. ## Step 4: Assign users to the app \[Okta] 1. In the **Okta Admin Console**, go to **Applications > your app > Assignments** 2. Select **Assign**, and assign **People** and **Groups** who can sign in to OX. 3. Select **Save**. ## Step 5: Enable app-initiated login and catalog visibility \[Okta] 1. In the **Okta Admin Console**, go to **Applications > your app** > **General** > **App Settings** > **Edit**. 2. **Login initiated by:** select **Either Okta or App**. 3. Select **Display application icon to users**. 4. **Initiate login URI:** Take the URL from the [Okta Configuration ](https://app.ox.security/settings?tab=login\&loginOption=Okta)dialog box (). > **Note:** For On-Prem\ > [`https://app.ox.security/sso-login?organization=`](https://app.ox.security/sso-login?organization=)`&organization_name=&display_name=Example:`\ > 5. Select **Save**. ## Step 6: Map Okta groups to OX roles \[Okta and OX] This step enables the automatic assignment of [OX Security roles](/admin-settings/roles) based on user groups in your IdP. There are the following types of roles: * Roles predefined by OX, * Custom roles. ### Create user groups for predefined roles Each predefined role group requires a prefix. The default is: OXApp-. You can change the default prefix to a custom one. **To change the default prefix:** 1. Go to **Settings > Login > \[IdP icon]** and enter a different prefix.
2. **Create IdP role groups:** In your IdP, go to **Directory > Groups** and create groups using these exact names (case-sensitive) for each OX role you want to sync: * OXApp-Admin * OXApp-Developer * OXApp-Dev Manager/Security Champion * OXApp-Policy Manager * OXApp-Read Only ### Create user groups for custom roles In case you have custom role(s) defined in OX, you need to create groups using the exact labels OX generates for your custom roles. The label is different from the custom role name. You can view the custom role label only in the instructions provided by OX within the Configuration dialog. **To locate the custom role label:** 1. Go to **Settings > Login > \[IdP icon]** and in the instruction box, select **+**. 2. Scroll down in the instructions box until you get to **Advanced settings (auto provisioning) - Setting roles**. 3. Read the procedure. The custom role label appears next to the custom role name in brackets. You cannot change it. 4. Use this label as the name of your new group in IdP. **For example:** I know that the admin defined a custom role called Executive Viewer. If I am looking for the label that OX generated for the custom role Executive Viewer, first I locate the custom role Executive Viewer in brackets and then I can see that OX generated a label for this custom role "OXApp-CustomRole1".
### **Complete the process** 1. **Map group attributes**: In your IdP, ensure you have groups attribute mapping enabled. 2. **Enable sync:** In OX, go to **Settings > Login > \[IdP icon]** and enable **Sync OX Group Roles** using the prefix you selected. 3. Select **Save**. 4. In the IdP, assign users who need that specific scope access as members of the corresponding group. ## Step 7: Map Okta groups to OX scopes \[Okta and OX] 1. In the **Okta Admin Console**, go to **Directory** > **Groups** 2. Select **Add group**. 3. Name the scope groups by using the following naming conventions.
App owner and other UI-visible scopes For scopes that are available in the OX scope selector: 1. In OX, click the **scope selector** in the top navigation bar (for example, **Entire Organization**). 2. Select the scope that you want to map. 3. Click the information icon next to the scope. 4. In the details panel, copy the value from the **SSO Group String** field. 5. Use the copied value as the Okta group name. The **SSO Group String** is generated automatically by OX. Example: ``` OXAppOwnerScope-DevOps-id:devops@acme.com ```
Tag scopes Tag scopes are not displayed in the scope selector, so OX does not generate an **SSO Group String** for them. Instead, create the Okta group name by using the following format: ``` OXTagScope--id: ``` Example: ``` OXTagScope-app-id:acme-app ``` Replace: * `` with the tag name. * `` with the unique ID of the tag. The tag ID is not available in the OX user interface. To obtain it, use the OX API to retrieve the tag details, and then use the returned tag ID when constructing the group name. > **Note:** Tag IDs can currently be retrieved only through the OX API by using the **Get Single Tag** endpoint.
4. Open each new group, select **Assign people**, and add the relevant users or groups. 5. Go to **Applications > your app >** **Sign On** . **OpenID Connect ID Token** . **Edit** 6. **Group claim type:** **Filter**. 7. **Group claim filter:** **groups** **Matches regex** `.*` 8. Select **Save**. 9. In the OX platform, go to **Settings > Login Settings** and enable **Sync OX Group Scopes**. ## Step 8: Test the sign-in \[OX] 1. In the OX platform, go to `https://.app.ox.security/`. 2. Select **Sign in with Okta** and sign in with a user you assigned. 3. If you configured the **Initiate login URI**, you can open that link to start the flow directly. ## Troubleshooting | Symptom | Where to fix | What to check | | ---------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | Invalid redirect URI | Okta | The **Sign-in redirect URIs** entry must exactly match `https://auth..app.ox.security/login/callback`. | | Invalid client or secret | OX and Okta | Paste the exact **Client ID** and **Client Secret** from the Okta app. Ensure the secret is valid. | | User not authorized to use the app | Okta | Applications → your app → **Assignments**. Ensure the user or their group is assigned. | | Roles do not match after sign-in | Okta and OX | Verify the user’s Okta group membership. Ensure **Group claim filter** includes groups and **Sync OX Group Roles/Scopes** is on in OX. | # SSO Okta Express Config This article describes how to set up SSO with Okta that is fast and secure. The feature includes: * **Service Provider (SP)-Initiated Authentication (SSO) Flow:** The authentication flow occurs when the user logs in to OX. * **Just-In-Time (JIT) Provisioning:** Users are automatically created on their first login. Email and name attributes are provisioned. * **Universal Logout:** When enabled, Okta can terminate user sessions and tokens when risk is detected or when an admin initiates logout. ## Just-in-time (JIT) provisioning With JIT provisioning enabled, users are automatically created in OX when they first sign in via Okta. * When a user authenticates via Okta for the first time, a new user account is automatically created with the email and name from Okta. * The user is granted access to OX immediately. **Attributes Provisioned** * Email address * Full name **Auto-provisioning of roles and scopes (optional)** See steps 5 and 6. ## Prerequisites * Okta admin rights to configure the setup. * Contact your OX support team to discuss if this approach aligns with your use case. ## Configuration steps * [Add the OX application in Okta](#step-1-add-the-ox-application-in-okta) * [Express configure SSO](#step-2-express-configure-sso) * [Enable universal logout](#step-3-enable-universal-logout) * [Assign users and test](#step-4-assign-users-and-test) * [Configure auto-provisioning for roles (optional)](#step-5-configure-auto-provisioning-for-roles-optional) * [Configure auto-provisioning for scopes (optional)](#step-6-configure-auto-provisioning-for-scopes-optional) ### Step 1: Add the OX application in Okta 1. In Okta, go to **Applications > Browse App Catalog**. 2. Search for OX and click **Add Integration**. 3. Click **Done**. ### Step 2: Express configure SSO 1. In the newly created OX application, click the **Sign On** tab. 2. Click E**xpress Configure & Universal UL**. 3. Select the organization you want to set up with Okta SSO. 4. When prompted for credentials, enter the admin email and temporary password provided by OX. Alternatively, use a Google or GitHub social login. 5. In the next screen, approve the connection with OX to complete the setup. ### Step 3: Enable universal logout 1. In the **Sign On** tab of the OX application. 2. Activate the checkbox **Okta system or admin initiates logout**. ### Step 4: Assign users and test Once OX has confirmed the setup is complete: 1. Assign the admin account to the OX application in Okta. 2. Assign any other users or groups that should have access to OX. 3. Test the login flow. Open [OX ](https://www.ox.security/)and log in with the admin account. 4. You should be automatically redirected to your Okta SSO login. ### Step 5: Configure auto-provisioning for roles (optional) Roles are provisioned in Okta. 1. In Okta, go to **Directory > Profile Editor**. 2. Search for a user of the app. 3. Set the name of the Roles variable to **userGroups**.
4. Select the user. 5. Click **Add Attribute** and add all the settings shown in the image.\ ![](/files/4WUrqNdyJ0dWU59HtizQ) 6. Click **Save and Add Another**.\ For the last user, click **Save**, not **Save and Add Another**. ### Step 6: Configure auto-provisioning for scopes (optional) Scopes are provisioned in Okta. 1. In Okta, go to **Directory > Profile Editor**. 2. Search for a user of the app. 3. Set the name of the Scopes variable to **userScopes**. 4. Select the user. 5. Click **Add Attribute** and add all the settings shown in the image. 6. Click **Save and Add Another**. 7. For the last user, click **Save**, not **Save and Add Another**. ## Universal logout When Universal Logout is enabled, Okta can terminate user sessions across all applications. The feature ensures that when a user is logged out of Okta, they are also logged out of OX. Universal logout is triggered when: * An administrator initiates a logout from the Okta Admin Console. * The Okta system detects risk and terminates sessions for security. ## Troubleshooting If you need help, reach out to [OX support](http://support@ox.security). # SSO with Microsoft Entra ID Microsoft Entra ID (formerly Azure Active Directory) supports OpenID Connect (OIDC) for secure single sign-in.\ OX supports OIDC SSO with Entra ID so your users can sign in to OX with their company credentials.\ This section matches the structure and tone of your Okta SSO page for consistency. ## Prerequisites * Entra admin permissions to register applications and manage Enterprise applications. * OX Owner or Admin permissions. ## Step 1: Register the application \[Entra] Create an application registration in Entra ID that represents OX. This app sets the redirect URI and provides the Application (client) ID you will use in OX. To register the application: 1. In the **Entra admin center**, go to **Applications** > **App registrations** > **New registration**, and set the following parameters: | Parameter | Description | | ---------------------------- | ------------------------------------------------------------------------------- | | **Name:** | Set the app name, for example, **OX Security SSO**. | | **Supported account types:** | **Accounts in this organizational directory only (Single tenant)**. | | **Redirect URI:** | **Platform:** **Web** \| **URL:** `https://auth.app.ox.security/login/callback` | 2. Select **Register**. ## Step 2: Create a client secret \[Entra] 1. Open the app **Certificates & secrets** page. 2. Select **New client secret**. 3. Enter a description and select an expiry period. 4. Select **Add**.
5. Copy and save the **Value** now. You will not see it again. ## Step 3: Configure SSO in OX \[OX] 1. In the OX platform, go to **Settings** > **Login Settings** and select **Microsoft Entra ID**. Take the values from the [Configuration ](https://app.ox.security/settings?tab=login\&loginOption=AzureAD)screen.
2. Fill the fields using as follows: | Parameter | Description | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Entra domain or Tenant (Directory) ID** | Enter your tenant primary domain (for example, `contoso.onmicrosoft.com`) or the Directory (tenant) ID GUID. | | **Application (client) ID** | Paste the **Application (client) ID** from the Entra app registration **Overview**. | | **Client Secret (Value)** | Paste the client secret value you created in Entra. | | **Enable auto provisioning** | Enable this if you want users to sign in without inviting them in the OX Members page and to control roles and scopes using Entra ID groups. **Note:** If you do not configure auto-provisioning with roles, users who are not invited sign in as **Read Only**. If you do configure roles, manage role assignments only in Entra ID. OX role changes are ignored for Entra SSO users. | | **Sync OX Group Roles** | When enabled, OX assigns a role (Admin, Developer, Policy Manager, Read Only) based on the user’s Entra ID group membership. Manage memberships in Entra ID. | | **Sync OX Group Scopes** | When enabled, OX grants data visibility based on Entra ID group names that represent application owner scopes or tag scopes. Manage memberships in Entra ID. | 3. Select **Save**. ## Step 4: Assign users to the Enterprise application \[Entra] 1. In the **Entra admin center**, go to **Enterprise applications** and open your app. 2. Go to **Users and groups**. 3. Select **Add user/group** and assign the people and groups who can sign in to OX. 4. Select **Assign**. ## Step 5: Enable app-initiated login and catalog visibility \[Entra] 1. In **App registrations** > your app > **Branding & properties**, set the following parameters: | Parameter | Value | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **Home page URL** | `https://app.ox.security/sso-login?organization=&organization_name=&display_name=&connection=waad-` | 2. In **Enterprise applications** > your app > **Properties**, set the following parameters: | Parameter | Value | | --------------------------------- | ------- | | **Enabled for users to sign-in?** | **Yes** | | **Assignment required?** | **Yes** | | **Visible to users?** | **Yes** | 3. Select **Save**. ## Step 6: Map Entra ID groups to OX roles \[Entra and OX] This step enables the automatic assignment of [OX Security roles](/admin-settings/roles) based on user groups in your IdP. There are the following types of roles: * Roles predefined by OX, * Custom roles. ### Create user groups for predefined roles Each predefined role group requires a prefix. The default is: OXApp-. You can change the default prefix to a custom one. **To change the default prefix:** 1. Go to **Settings > Login > \[IdP icon]** and enter a different prefix.
2. **Create IdP role groups:** In your IdP, go to **Directory > Groups** and create groups using these exact names (case-sensitive) for each OX role you want to sync: * OXApp-Admin * OXApp-Developer * OXApp-Dev Manager/Security Champion * OXApp-Policy Manager * OXApp-Read Only ### Create user groups for custom roles In case you have custom role(s) defined in OX, you need to create groups using the exact labels OX generates for your custom roles. The label is different from the custom role name. You can view the custom role label only in the instructions provided by OX within the Configuration dialog. **To locate the custom role label:** 1. Go to **Settings > Login > \[IdP icon]** and in the instruction box, select **+**. 2. Scroll down in the instructions box until you get to **Advanced settings (auto provisioning) - Setting roles**. 3. Read the procedure. The custom role label appears next to the custom role name in brackets. You cannot change it. 4. Use this label as the name of your new group in IdP. **For example:** I know that the admin defined a custom role called Executive Viewer. If I am looking for the label that OX generated for the custom role Executive Viewer, first I locate the custom role Executive Viewer in brackets and then I can see that OX generated a label for this custom role "OXApp-CustomRole1".
### **Complete the process** 1. **Map group attributes**: In your IdP, ensure you have groups attribute mapping enabled. 2. **Enable sync:** In OX, go to **Settings > Login > \[IdP icon]** and enable **Sync OX Group Roles** using the prefix you selected. 3. Select **Save**. 4. In the IdP, assign users who need that specific scope access as members of the corresponding group. ## Step 7: Map Entra ID groups to OX scopes \[Entra and OX] ### Step 7: Map Entra ID groups to OX scopes Map your Microsoft Entra ID groups to the corresponding OX scopes. #### For App owner and other UI-visible scopes For scopes that are available in the OX scope selector: 1. In OX, click the **scope selector** in the top navigation bar (for example, **Entire Organization**). 2. Select the scope that you want to map. 3. Click the information icon next to the scope. 4. In the details panel, copy the value from the **SSO Group String** field. 5. In Microsoft Entra ID, use the copied value as the group name. The **SSO Group String** is generated automatically by OX. Example: ``` OXAppOwnerScope-Support-id:raz.levi@ox.security ``` #### For tag scopes Tag scopes are not displayed in the scope selector, so OX does not generate an **SSO Group String** for them. Instead, construct the group name by using the following format: ``` OXTagScope--id: ``` Example: ``` OXTagScope-Production-id:3b6d9f2a-8c4e-4d0f-9b2a-7d45f9f7b123 ``` Replace: * `` with the tag name. * `` with the unique ID of the tag. The tag ID is not available in the OX user interface. To obtain it, use the OX API to retrieve the tag details, and then use the returned tag ID when constructing the group name. > **Note:** Tag IDs can currently be retrieved only through the OX API. Use the **Get Single Tag** API endpoint to retrieve the tag ID. ## Step 8: Test the sign-in \[OX] 1. In the OX platform, go to `https://app.ox.security/` or your environment URL. 2. Select **Sign in with Microsoft** and sign in with an assigned user. 3. If you configured the **Home page URL** in Step 5, open that link to start the flow. ## Troubleshooting | Symptom | Where to fix | What to check | | ------------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Reply URL mismatch | Entra | The **Redirect URI** must exactly match `https://auth.app.ox.security/login/callback`. | | Invalid client secret | Entra and OX | Paste the secret **Value** in OX and verify it is not expired. | | User not authorized to use the app | Entra | **Enterprise applications** → your app → **Users and groups**. Ensure the user or their group is assigned. | | Roles or scopes do not match after sign-in | Entra and OX | Verify the user’s Entra group membership, ensure group claims are in the ID token, and confirm **Sync OX Group Roles** or **Sync OX Group Scopes** is on in OX. | # Connect Your Source Control OX Security integrates directly with a wide range of source control systems, providing complete visibility into the security posture of your code from the earliest stages of development. By connecting your source control platforms, whether hosted in the cloud, on-premises, or hybrid, you can continuously scan repositories for vulnerabilities, secrets, misconfigurations, open source risks, and compliance violations. Why connect your source control system: * **Shift security left** by identifying issues in code as soon as it's written. * **Automatically scan** all repositories, including new ones, with minimal manual effort. * **Map findings to code ownership** by linking vulnerabilities to specific commits, pull requests, and authors. * **Unify visibility** across your entire codebase, regardless of where it’s hosted or how it’s structured. * **Maintain coverage** across SaaS-hosted and self-managed environments without duplicating effort. ## Supported systems OX currently supports integration with the following source control platforms: * [GitHub](/get-started/onboarding-to-ox/source-control/github) * [GitLab](/get-started/onboarding-to-ox/source-control/gitlab) * [Bitbucket Cloud](/get-started/onboarding-to-ox/source-control/bitbucket) * [Bitbucket Data Center / Server](/get-started/onboarding-to-ox/source-control/bitbucket) * [Azure Repos](/get-started/onboarding-to-ox/source-control/azure) * Azure TFS (Team Foundation Server / Azure DevOps Server) * AWS CodeCommit * Gerrit Code Review # Connection Methods OX supports multiple connection methods so you can connect source control systems, cloud platforms, and security tools using an approach that matches your deployment model, security posture, and permission requirements.\ Each method represents a common integration pattern used across OX connectors. ## How to choose a connection method Select a connection method based on where your systems are hosted, how access is managed in your organization, and whether your environment allows inbound connectivity. SaaS environments typically use App, Identity Provider, or Token connections.\ On-prem or restricted environments require OX Broker. OX supports several connection methods that follow common integration patterns across connectors. Each method differs in how authentication is handled, how permissions are managed, and how connectivity is established. ### App The App method is the most **straightforward and easy to apply**. It uses a standard OAuth-based installation flow that can be completed with minimal configuration. During setup, permissions are requested and scoped automatically, lowering configuration overhead and reducing the steps you need to take. Because the integration is managed and permissions are granted through a guided install process, this method is ideal for quick onboarding. ### Identity Provider The Identity Provider method relies on an external authentication system such as SSO, allowing users to authenticate through a centralized identity service instead of managing tokens directly. This method removes the need for API token handling while providing federated access using established identity standards. It’s simple in terms of credential management and works well if you already use an identity provider for access control. ### Token The Token method uses direct API credentials to create the connection. Tokens can be scoped with **granular permissions**, letting you control exactly what resources OX can access. This pattern is common when an organization requires fine-tuned access restrictions or must comply with strict security policies. Unlike managed App integrations that abstract permission details, this method makes permissions explicit and configurable. ### OX Broker OX Broker is a secure, containerized service that runs in your environment and enables communication between internal resources and OX services. Instead of requiring inbound access from the internet, the broker initiates a secure outbound connection to OX. This reverses the traditional connectivity model, removing the need for open inbound ports or whitelisted IPs. It’s particularly useful for restricted or on-premises environments where network security or internal access constraints are high. ## Connection methods comparison | Method | Deployment model | Primary use | Token management | Permission control | Network model | Recommended when | | ----------------- | -------------------- | -------------------------- | ---------------------- | ---------------------- | ------------- | ------------------------------------- | | App | SaaS | Managed integration | Not required | Limited | Outbound | Fast setup is preferred | | Identity Provider | SaaS | Centralized authentication | Not required | Limited | Outbound | Central identity is in place | | Token | SaaS | Direct API access | Required | Full | Outbound | Fine-grained permissions are required | | OX Broker | On-Prem / Restricted | Internal system access | Depends on integration | Depends on integration | Outbound-only | Inbound connectivity is restricted | ### Notes * Not all connectors support all connection methods. * Available methods are listed on each connector’s setup page. * Some connectors support multiple methods to address different deployment scenarios. # GitHub GitHub provides cloud-based hosting for software development and version control using Git. It offers distributed version control and source code management capabilities. By connecting GitHub to OX, you enable the system to map your applications and scan them for security issues. In addition, when connecting GitHub, GitHub Actions is a CI/CD platform that automates the build, test, and deployment pipeline. Before deciding on the connection method you are going to use, learn about [the connection methods used in OX](/get-started/onboarding-to-ox/source-control/connection-methods). The following connection methods are available: * [GitHub App](/get-started/onboarding-to-ox/source-control/github/github-app) * [GitHub Identity Provider](/get-started/onboarding-to-ox/source-control/github/github-identity-provider) * [GitHub Token](/get-started/onboarding-to-ox/source-control/github/github-token) ### GitHub Server Options * **GitHub.com (Public SaaS)**: If you are using the public GitHub server, you can log in using either the Identity Provider or Token method. The Token method defaults to the public GitHub server address. * **GitHub Enterprise (Private Server)**: If you are using a private GitHub instance, select the Token login option and provide your GitHub server URL. ## Connecting Multiple Accounts You can connect multiple source control accounts within the same organization, securing them all under a single organization in the OX platform. For instance, you can connect multiple GitLab accounts under one organization using multiple token connections, multiple identity providers, or multiple apps connections. Integrating with multiple accounts is especially beneficial for large organizations where different departments may need separate credentials to access different GitLab instances or other services. The integration is flexible and robust because you can combine different connection methods, such as using tokens for more sensitive accounts and apps and identity providers for less sensitive ones. # GitHub App The GitHub App method offers a streamlined way to connect an OX platform account to GitHub. This method uses an application created by OX Security, which simplifies the connection process. When using this method, you install the OX GitHub app into your GitHub organization. The app is granted permissions to access your GitHub data, allowing the OX platform to interact with your repositories. For details about the permissions requested by the app and how they are used, see [OX GitHub App Permissions](/get-started/onboarding-to-ox/source-control/github/github-app/ox-security-github-app-permissions). The following process describes the OX-generated GitHub App configuration. In addition to the OX-generated option, which is the recommended option, you can define a [self-hosted GitHub App configuration](/get-started/onboarding-to-ox/source-control/github/github-app/creating-a-self-hosted-ox-github-app). **To connect with GitHub App:** 1. In the **OX** platform, go to **Connectors** and select **GitHub > GITHUB APP**.
2. Select **CONNECT**. You are automatically redirected to the source control system’s authentication dialog. 3. Login to GitHub. The **Install OX Security** dialog appears with the list of organizations that you have defined on GitHub.
4. Select the organization with which you want to set up the GitHub-OX integration.
5. In the **Install & Authorize OX Security** dialog, select as follows: * **All repositories:** Grants OX GITHUB APP permissions to all the GitHub repositories within the selected GitHub organization. * **Only select repositories:** Select GitHub repositories to which you want to grants OX GITHUB APP permissions within the selected GitHub organization. 6. Select **Install & Authorize**. The connection is established and you are redirected back to OX Security, where the list of all the repositories that participate in the integration appears.
7. Select the repos you want to scan and click **SAVE**. 8. (optional) [Select branches you want to scan within the selected repos.](/scan-and-analyze-with-ox/scanning/multi-branch-support) 9. (optional) To connect more GitHub accounts to the same organization in the OX platform, select **Add another GitHub App +**, add the app and select **CONNECT**. ### What's Next? After connecting GitHub to OX using app, you can integrate OX with your CI/CD pipelines to automate scanning and report results to pull requests. OX supports multiple pipeline integration methods, including [GitHub App](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/app-pipeline-integration/github-app) integration, [webhook-based](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/webhooks-pipeline-integration) integrations, and direct CI/CD integrations. # 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 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 | Recommended option: **Read + write variant** (default) | | Scan your code, surface findings in the OX UI, and let your team handle remediation manually | Not recommended option: **Read-only variant** | ### Capability comparison | Capability | Read + write | Read-only | | ------------------------------------------------------------------------------------------------- | ------------------------- | -------------- | | 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 and remediation | Detection only | | One-click auto-fix pull requests | Yes | No | | Inline PR review comments on findings | Yes | No | | OX summary comment on pull requests | Yes | No | | Remediation of branch protection, repo settings, Actions permissions, and collaborator membership | Yes | No | | Clean uninstall from the OX UI | Yes | No | ### 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. ### Permission details The table below lists every permission OX requests, the access level for each variant, why you need it, and what stops working if you don't grant it. | Status | Permission | Read + write variant | Read-only variant | Why you need it | If you don't grant this | | ------------------------------------ | ------------------------------------ | -------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Required | **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. | | Required (read), Optional (write) | **Code (contents)** | Read and write | Read | 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 | **Checks** | Read and write | 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. | | Optional (high value) | **Pull requests** | Read and write | Read | Read gives you per-PR scanning, code-review policy posture (for example, *Pull request merged without review*), and accurate attribution of who introduced a finding. Write (read + write variant only) lets OX open auto-fix PRs, post inline review comments at the exact file and line of a finding, request reviewers, and update or dismiss past reviews as findings evolve. | Without read: per-PR scanning, code-review policies, and commit-to-pull-request mapping stop. Branch-level scanning continues. Without write (read + write variant only): auto-fix PRs can't be opened, and OX can't post inline review comments. | | Optional | **Issues** | Read and write | Read | Read lets OX deduplicate comments when posting findings on pull requests, keeping the PR conversation clean. Write (read + write variant only) lets OX post and update its summary comment on a pull request. GitHub treats top-level PR comments as "issue comments". | Without read: pull request comment deduplication may be less effective. Without write (read + write variant only): the OX summary comment won't appear on pull requests. Inline review comments still work if you grant **Pull requests** write. | | Optional | **Actions** | Read and write | Read | Read gives you GitHub Actions and CI/CD posture findings (insecure third-party actions, fork pull request workflow rules, overly permissive Actions tokens). Write (read + write variant only) lets OX remediate Actions misconfigurations in one click, for example restricting default workflow permissions to read-only and disabling workflow approval of pull requests. | Without read: all GitHub Actions and CI/CD posture findings are unavailable. Without write (read + write variant only): detection still works, but your team will need to apply the fix manually using the guidance in the OX UI. | | Optional | **Administration** | Read and write | Read | Read gives you branch protection and ruleset compliance findings (*Branch lacks required reviews*, *Rulesets bypassable by admins*). Write (read + write variant only) lets OX remediate branch protection rules and repository settings (require reviews, require signed commits, disallow deletion or force pushes, set repo private, archive, disallow forking) when you accept the fix in the OX UI. | Without read: branch-protection and ruleset compliance findings are unavailable. Without write (read + write variant only): detection still works, but your team will need to apply the fix manually. | | Optional | **Members** | Read and write | Read | Read gives you RBAC and access-control findings (outside collaborators, admin sprawl, missing two-factor authentication enforcement). Write (read + write variant only) lets OX remove a collaborator or change a collaborator's permission level (pull, triage, push, maintain, admin) when you accept the fix. | Without read: all RBAC and access-control posture findings are unavailable. Without write (read + write variant only): detection still works, but OX can't apply the membership change on your behalf. | | Optional | **Organization administration** | Read | Read | Read gives you org-level audit-log analysis and discovery of installed apps. Write (read + write variant only) lets OX remove an organization member or change their org role, flip the org-level *Allow forking of private repositories* setting, and cleanly uninstall the OX GitHub App when you disconnect from the OX UI. | Without read: org-level audit-log analysis is unavailable. Without write (read + write variant only): org-level remediations are unavailable, and uninstalling the app must be done from the GitHub UI rather than from OX. | | Optional (read + write variant only) | **Workflows** | Write | Not requested | So OX's auto-fix pull requests can include changes to workflow files (`.github/workflows/*.yml`), for example bumping an action version as part of an SCA fix. GitHub treats workflow files as a separate scope and doesn't define a read level for it. | Auto-fix PRs that touch workflow files are rejected by GitHub. Auto-fix PRs that don't touch workflow files continue to work. | | Optional | **Dependabot alerts** | Read | 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. | | Optional | **Secret scanning alerts** | Read | 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. | | Optional | **Security events** | Read | 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. | | Optional | **Repository hooks** | Read | Read | So OX can detect insecure webhooks that could leak repository data (for example, webhook URLs without SSL verification). | Webhook posture findings become unavailable. | | Reserved | **Commit statuses** | Read | Read | Reserved for upcoming commit-status posture analysis. | No impact on current functionality. | | Reserved | **Deployments** | Read | Read | Reserved for upcoming deployment-tracking findings. | No impact on current functionality. | | Reserved | **Pages** | Read | Read | Reserved for upcoming GitHub Pages posture analysis. | No impact on current functionality. | | Reserved | **Packages** | Read | Read | Reserved for upcoming GitHub Packages security analysis. | No impact on current functionality. | | Reserved | **Repository projects** | Read | Read | Reserved for upcoming repository-projects posture analysis. | No impact on current functionality. | | Reserved | **Custom repository roles** | Read | Read | Reserved for upcoming custom-role posture analysis on organization custom roles. | No impact on current functionality. | | Reserved | **Organization events** | Read | Read | Reserved for upcoming organization-event analysis. The organization audit log itself is covered under **Organization administration**. | No impact on current functionality. | | Reserved | **Organization hooks** | Read | Read | Reserved for upcoming organization-level webhook posture analysis. | No impact on current functionality. | | Reserved | **Organization projects** | Read | Read | Reserved for upcoming organization-projects posture analysis. | No impact on current functionality. | | Reserved | **Organization self-hosted runners** | Read | Read | Reserved for upcoming self-hosted runner security analysis. | No impact on current functionality. | | Reserved | **Organization user blocking** | Read | Read | Reserved for upcoming user-blocking posture analysis. | No impact on current functionality. | | Optional | | | | | | # Connecting with Self-Hosted OX GitHub App ## Connect using a self-hosted GitHub App If you run GitHub Enterprise Server in your own environment, you cannot install the public OX GitHub App from github.com. Instead, you register a dedicated OX GitHub App directly inside your GitHub Enterprise instance and share its credentials with OX Security. This page describes how to create and configure that GitHub App. For an overview of the standard (SaaS) GitHub App flow and other connection methods, see [GitHub](/get-started/onboarding-to-ox/source-control/github). Use this connection method when: * Your source code is hosted on GitHub Enterprise Server rather than github.com. * You want to authenticate using a GitHub App. * Your GitHub Enterprise Server is reachable from OX directly or through an OX Broker. ### Process overview Connecting a self-hosted GitHub App requires actions from both your organization and OX. 1. Generate a webhook secret. 2. Create and configure a GitHub App in your GitHub Enterprise Server. 3. Configure the required permissions and subscribed events. 4. Generate the app credentials. 5. Share the required app details with OX. 6. OX registers the GitHub App, completes the required backend configuration, and enables GitHub App support for your organization. 7. Install the GitHub App in your GitHub Enterprise organization. 8. Connect GitHub in OX and select the repositories and branches to scan. ### Before you begin Make sure you have the following: | Requirement | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GitHub Enterprise access | Organization owner permissions for the GitHub Enterprise organization where the app will be registered. | | GitHub Enterprise URL | The URL of your GitHub Enterprise Server. | | OX Broker (if applicable) | If your GitHub Enterprise instance is not reachable from the public internet, deploy the [OX Broker](/get-started/onboarding-to-ox/prerequisites-and-access/ox-broker) in your environment first. | | OX Customer Success contact | OX provides the instance-specific values required during the setup, including the callback URL, webhook URL, and `appId`. | ### Step 1: Generate a webhook secret The webhook secret is a 40-character random string that GitHub uses to sign webhook payloads sent to OX. Generate the secret locally. **Linux or Windows (WSL/Git Bash)** ``` tr -dc a-z0-9 **Developer settings** > **GitHub Apps**. 2. Select **New GitHub App**.
3. Configure the following settings. | Setting | Value | | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **GitHub App name** | `OX GitHub App` (for example, `OX Acme GitHub App`) | | **Description** | A short description, such as `OX GitHub App` | | **Homepage URL** | `` | | **Callback URL** |

\/github-app-installation-configure?appId=\
Note: Your OX Customer Success representative provides the values for appId and \. These values must exactly match the configuration registered on the OX side.

| | **Expire user authorization tokens** | Cleared | | **Request user authorization (OAuth) during installation** | Selected | | **Enable Device Flow** | Cleared | | **Setup URL (optional)** | Leave empty | | **Redirect on update** | Selected | 4. Under **Webhook**, configure the following:
SettingValue
ActiveSelected
Webhook URL<ox-instance-url>/api/githubapp/<customer-name>/webhooks
Note: Your OX Customer Success representative provides the values for <ox-instance-url> and <customer-name>. These values must exactly match the configuration registered on the OX side.
SecretThe webhook secret generated in Step 1
### Step 3: Configure permissions Configure the GitHub App permissions as shown below. Leave every permission that is not listed set to **No access**. #### Repository permissions | Permission | Access | | ----------------------------------------------- | --------------------- | | Actions | Read and write | | Administration | Read and write | | Agent secrets | No access | | Agent tasks | No access | | Agent variables | No access | | Artifact metadata | No access | | Attestations | No access | | Checks | Read and write | | Code quality | No access | | Code scanning alerts | Read-only | | Codespaces | No access | | Codespaces lifecycle admin | No access | | Codespaces metadata | No access | | Codespaces secrets | No access | | Commit statuses | Read-only | | Contents | Read and write | | Copilot agent settings | No access | | Custom properties | No access | | Dependabot alerts | Read-only | | Dependabot secrets | No access | | Deployments | Read-only | | Discussions | No access | | Environments | No access | | Issues | Read and write | | License compliance alerts | No access | | Merge queues | No access | | Metadata | Read-only (mandatory) | | Packages | Read-only | | Pages | Read-only | | Projects | Read-only | | Pull requests | Read and write | | Repository security advisories | No access | | Secret scanning alert dismissal requests | No access | | Secret scanning alerts | Read-only | | Secret scanning push protection bypass requests | No access | | Secrets | No access | | Single file | No access | | Variables | No access | | Webhooks | Read-only | | Workflows | Read and write | #### Organization permissions | Permission | Access | | ----------------------- | -------------- | | Administration | Read-only | | Blocking users | Read-only | | Custom repository roles | Read-only | | Events | Read-only | | Members | Read and write | | Projects | Read-only | | Self-hosted runners | Read-only | | Webhooks | Read-only | #### Account permissions Leave all account permissions set to **No access**. ### Step 4: Subscribe to events Select only the following events: * Meta * Check run * Check suite * Merge group * Pull request * Push * Repository Leave all other events cleared.
### Step 5: Choose where the app can be installed 1. Under **Where can this GitHub App be installed?**, select **Only on this account**.
2. Select **Create GitHub App**. ### Step 6: Generate the private key 1. On the GitHub App page, select **Generate a private key**.
2. Save the downloaded `.pem` file in a secure location. GitHub displays the private key only once. If you lose it, you must generate a new one. ### Step 7: Generate the client secret 1. On the GitHub App page, scroll to **Client secrets**. 2. Select **Generate a new client secret**.
3. Copy the generated value immediately. GitHub displays the client secret only once. ### Step 8: Collect the app identifiers 1. From the **App's settings** page, copy the following values from the **About** section:
* **App ID** (numeric, for example, `941975`). * **Client ID** (for example, `Iv23liJFWBwZiGNQIrJV`). 2. Also note the App's **URL slug**, which appears in the GitHub URL after `/settings/apps/`: ``` /settings/apps/ ``` For example:
``` https://github.example.com/settings/apps/ox-acme-github-app ``` The URL slug is: ``` ox-acme-github-app ``` ### Step 9: Share the values with OX Provide the following information to your OX Customer Success representative through a secure channel. | Value | Source | | ----------------------------------------- | --------------------------------------------------------------------------------------------------- | | **GitHub Enterprise server instance URL** | The full URL of your GitHub Enterprise instance (for example, `https://github..com`). | | **Webhook secret** | The 40-character string generated in Step 1. | | **Private key** | The `.pem` file downloaded in Step 6. | | **App ID** | From the App's **About** section (Step 8). | | **Client ID** | From the App's **About** section (Step 8). | | **Client secret** | The value generated in Step 7. | | **URL slug** | From the App's GitHub URL (Step 8). | > **Note:** > > Treat the private key, client secret, and webhook secret as sensitive credentials. Share them only through a secure channel. ### Step 10: Install the App and Complete the Connection in OX After OX confirms that your App has been registered on the OX side: 1. In GitHub Enterprise, open the App's settings page and select **Install App**. 2. Choose the organization to install the App on, and select **All repositories** or **Only select repositories** based on what you want OX to scan. 3. Select **Install & Authorize**. 4. In the OX platform, go to **Connectors** and select **GitHub > GITHUB APP**. The list of repositories from the installation appears. 5. Select the repositories you want OX to scan and select **SAVE**. 6. (Optional) Select branches to scan within those repositories. If your GitHub Enterprise instance is not reachable from the public internet, make sure the [OX Broker](https://claude.ai/get-started/onboarding-to-ox/prerequisites-and-access/ox-broker.md) is installed and configured to point at your GitHub Enterprise URL before completing the steps above. ### Related Topics * [GitHub connector](/get-started/onboarding-to-ox/source-control/github) * [OX Broker](/get-started/onboarding-to-ox/prerequisites-and-access/ox-broker) # GitHub Identity Provider The Identity Provider (IDP) method is another way to link GitHub to OX Security. This method relies on authentication services provided by GitHub or a third-party service. The user connects using their GitHub account credentials, allowing the OX platform to use GitHub as the identity provider for authentication. **To connect with Identity Provider:** 1. In the **OX** platform, go to **Connectors** and select **GitHub > IDENTITY PROVIDER**.
2. Select **CONNECT**. You are automatically redirected to the source control system’s authentication dialog. 3. Log in to GitHub and grant permissions to access the data.
2. Select **Authorize oxsecurity**. The connection is established and you are redirected back to OX Security, where the list of all the repositories that participate in the integration appears.
7. Select the repos you want to scan and select **SAVE**. 8. (optional) [Select branches you want to scan within the selected repos.](/scan-and-analyze-with-ox/scanning/multi-branch-support) 9. To connect more GitHub accounts to the same organization in the OX platform, select **Add another Identity Provider +**, set the required parameters and select **CONNECT**. # GitHub Token The Token method provides the most flexibility for connecting GitHub to OX Security. In this method, users generate an API token in GitHub, which serves as a security credential to allow OX Security access to specific repositories and actions. **To connect with Token:** 1. [Get a GitHub token.](/get-started/onboarding-to-ox/source-control/github/github-token/getting-github-tokens) 2. In the **OX** platform, go to **Connectors** and select **GitHub > TOKEN**.
3. In the **Configure your GitHub credentials** dialog, set the following parameters:
ParameterDescription
GitHub Host URLAdd your GitHub organization account URL.
TokenPaste the GitHub token you have created.
Connection NameThe token name is automatically generated by OX app.
You can change/edit the connection name at any time.
OX BrokerEnable this option to connect GitHub through an OX Broker instead of a direct connection. When enabled, OX routes communication through the broker, allowing access to GitHub instances that are not directly reachable from the internet. After enabling the toggle, provide the broker connection details as described in the OX Broker documentation.
4. To select specific repositories for scanning by OX platform, select the gear icon next to **DELETE**.
5. Select the repos you want to protect.
6. Select **SAVE**. 7. (optional) [Select branches you want to scan within the selected repos.](/scan-and-analyze-with-ox/scanning/multi-branch-support) 8. To connect more GitHub accounts to the same organization in the OX platform, select **Add another Token +**, set the required parameters and select **CONNECT**. # Getting GitHub Tokens When integrating with [GitHub](/get-started/onboarding-to-ox/source-control/github) source control and [GitHub Issues](/ticketing-and-messaging/ticket-management/github-issues), you need to get GitHub tokens. **To get GitHub tokens:** 1. Log in to your GitHub account. 2. From your profile picture in the top-right corner select **Settings**, then scroll down and select **Developer settings**.
3. In the **Developer settings** page, select **Personal access tokens > Tokens (classic)** and define the parameters as follows.
| Parameter | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | A significant name that makes it easy to identify the purpose of the token. | | **Expiration** | Set the expiration date as far as possible. | | **Select scopes** |

By selecting scopes you define the access permissions.

For GitHub source control - OX integration, select the following scopes:

  • repo
  • read:packages
  • read:org
  • read:repo\_hook
  • read:user
  • user:email
  • read:audit\_log

For GitHub Issues - OX integration, select the following scopes:

  • repo
  • project
  • read:user
| 4. Select **Update token**.
5. Copy the token and store it in a different location.\ After closing this dialog you cannot see it again. # GitLab GitLab is a complete DevOps platform that provides source code management, CI/CD pipelines, security testing, package registries, and collaboration capabilities in a single application. Connecting GitLab to OX enables OX to discover repositories, analyze source code, scan open source dependencies, monitor security posture, and correlate findings across your software development lifecycle. ### What OX adds * **Context and correlation:** OX maps GitLab findings to applications, services, and teams to show impact and ownership. * **Prioritization with severity factors:** OX may reprioritize scanner severities when exploitability and environment context reduce risk (for example, Critical → High). Severity factors explain why the priority changed. * **Evidence at a glance:** When available, OX displays scanner evidence, file locations, merge request information, and remediation guidance alongside OX analytics to speed triage. ### Terminology mapping GitLab and OX use different labels for similar concepts. Use this quick map while you work. | GitLab | OX Security | | ------------------ | ------------------ | | Projects | Applications | | Merge Requests | Pull Requests | | CI/CD Pipelines | CI/CD Pipelines | | Container Registry | Container Registry | | Vulnerabilities | Issues | | Security Findings | Findings | | Members | Users | ## Connection methods For general information about connection methods, see the article Connection methods. There are two options to connect GitLab to OX. | Connection Method | Details | | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | [Identity Provider](/get-started/onboarding-to-ox/source-control/gitlab-1/gitlab-identity-provider) | Use your existing identity provider connection for centralized authentication and repository access management. | | [Personal Access Token](/get-started/onboarding-to-ox/source-control/gitlab-1/gitlab-token) | Use a GitLab Personal Access Token (PAT) with the required scopes to authenticate and import repositories. | ## Prerequisites ### Prerequisites for all connection methods | Prerequisite | Description | | -------------- | ------------------------------------------------------------ | | OX permissions | Permission to configure connectors | | GitLab access | Access to the GitLab projects and groups you want to connect | # GitLab Identity Provider Use this connection method to connect GitLab to OX using OAuth authentication. During the connection process, you authenticate to GitLab and grant OX access to the GitLab resources that you want to scan. ### Before you begin Verify that: * You have permission to configure connectors in OX. * You have access to the GitLab projects and groups that you want OX to scan. ### Connect GitLab to OX 1. In OX, go to **Settings > Connections**. 2. Select **GitLab** **>** **Identity Provider**.
3. In **Connection Name**, enter a name for the connection. 4. Select **Connect**. > **Note** > > When you select **Connect**, GitLab prompts you to authorize OX to access your organization's resources. You must explicitly approve this access to complete the connection. ## GitLab SSO session requirements When you connect GitLab to OX using the **Identity Provider** authentication method, OX accesses GitLab on behalf of the user who created the connection. If your organization requires users to authenticate to GitLab through Single Sign-On (SSO), the GitLab session for the connected user must remain valid for OX to access repositories. ### How it works If GitLab is configured to require SSO through an Identity Provider (IdP): 1. A user connects GitLab to OX using the **Identity Provider** authentication method. 2. OX uses that user's GitLab authorization when accessing repositories. 3. OX can clone repositories only while the user's GitLab SSO session remains valid. If the GitLab SSO session expires, OX can no longer authenticate to GitLab and repository scans fail until the user signs in to GitLab again. For example, if your organization configures GitLab SSO sessions to expire every 24 hours, the user who connected GitLab to OX must sign in to GitLab again at least every 24 hours to keep repository scanning working. > **Important:** > > If repository scans unexpectedly stop working after an SSO session expires, have the user who connected the GitLab integration sign in to GitLab again to refresh the SSO session. ### Recommended approach for organizations with short SSO sessions If your organization enforces short-lived GitLab SSO sessions or frequent reauthentication, OX recommends connecting GitLab using a **Token** created for a dedicated service account instead of using the **Identity Provider** authentication method. Using a service account token provides more reliable access for automated repository scanning because it does not depend on an individual user's active GitLab SSO session. # GitLab Token Use this method to connect GitLab to OX by using a Personal Access Token (PAT). This method authenticates OX with your GitLab account and allows OX to discover and scan the projects that are accessible to that account. ### Before you begin Verify that: * You have permission to configure connectors in OX. * You have permission to create Personal Access Tokens in GitLab. * You have access to the GitLab projects and groups that you want OX to scan. ### Step 1: Create a Personal Access Token 1. Sign in to GitLab. 2. Go to **User Settings > Access Tokens**. 3. Select **Add new token**.
4. Enter a name for the token. 5. Optional: Specify an expiration date. 6. Select the following scopes: * `api` * `read_user` * `read_registry` 7. Select **Create personal access token**. 8. Copy the generated token.
> **Note** > > GitLab displays the token only once. Store it securely before leaving the page. ### Step 2: Connect GitLab to OX 1. In OX, go to **Settings > Connections**. 2. Select **GitLab**.
3. Open the **Token** tab. 4. Configure the connection. | Parameter | Description | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **GitLab Host URL** | The URL of your GitLab instance. For GitLab.com, enter `https://gitlab.com`. For a self-managed GitLab instance, enter your GitLab server URL. | | **Token** | The Personal Access Token (PAT) that you created in GitLab. | | **Connection Name** | A unique name for the connection. | | **OX Broker** | Enable this option to connect GitLab through an OX Broker instead of a direct connection. When enabled, OX routes communication through the broker, allowing access to GitLab instances that are not directly reachable from the internet. After enabling the toggle, provide the broker connection details as described in the OX Broker documentation. | | **Bypass SSL Verification** | Enable to skip SSL certificate validation. Use only if your environment uses self-signed or otherwise untrusted certificates. Not recommended because it reduces connection security. | 5. Select **Verify Connectivity**. 6. Select **Connect**. # Bitbucket Integrate Bitbucket Cloud with OX to centralize repository security findings alongside container, pipeline, cloud, and runtime signals already in OX. OX scans Bitbucket repositories on a schedule and on demand, enriches findings with OX context (application mapping, workflows, and compliance), and presents a unified queue for investigation and reporting. After you connect, Bitbucket scan results appear in the Active issues page (use the filter\ **Source tool > Bitbucket Cloud**). ## What OX adds * **Context and correlation:** OX maps Bitbucket findings to applications, services, and teams to show impact and ownership. * **Prioritization with severity factors:** OX may reprioritize scanner severities when exploitability and environment context reduce risk (for example, Critical → High). Severity factors explain why the priority changed. * **Evidence at a glance:** When available, OX displays scanner evidence, file locations, and remediation guidance alongside OX analytics to speed triage. ## Terminology mapping Bitbucket and OX use different labels for similar concepts. Use this quick map while you work.
Bitbucket CloudOX Security
PipelinesCI/CD Pipelines
RepositoriesApplications
## Connection methods For general information about connection methods, see the article [Connection methods](/get-started/onboarding-to-ox/source-control/connection-methods). There are three options to connect Bitbucket Cloud to OX.
Connection MethodDetails
Bitbucket App (recommended)Use the OX-created application for streamlined connection with app-level permissions. Simplifies installation and authorization.
Identity ProviderUse your existing connection for centralized authentication.
User name and passwordUse Bitbucket app passwords for basic authentication with granular permission control.
## Prerequisites #### Prerequisites for all connection methods | Prerequisite | Description | | ---------------------- | -------------------------------------------------------------- | | OX permissions | Permission to configure connectors | | Bitbucket Cloud access | Access to the Bitbucket Cloud workspace(s) you want to connect | #### Additional prerequisites by connection method
Connection MethodPrerequisites
Bitbucket appPermission to install apps in the workspace
Identity provider (IdP)Access to Bitbucket Cloud using an OAuth connection and Bitbucket Cloud administrator access
User name and passwordBitbucket account with permission to generate app passwords
## Connect with the OX Bitbucket app The Bitbucket App method uses an OX-created application to simplify connection. The app requests read access to repositories and branches, pull requests, and pipeline configuration results. 1. Verify that the [prerequisites](#prerequisites) are in place. 2. In OX, go to **Connectors** and select **Bitbucket Cloud > BITBUCKET APP**.
3. Select **CONNECT**. OX validates the credentials. 4. The **Grant access** dialog opens.
5. In **Configure your Bitbucket Cloud connector**, select the repos you want OX to scan.
6. Select **SAVE**. 7. In **Configure your Bitbucket Cloud credentials**, select **VERIFY CONNECTIVITY.**
A green success message at the bottom of the screen indicates a successful connection. If verification fails, check your credentials and permissions. #### Optional configurations * To change the repositories OX scans and monitors, see the section [Change the repositories OX scans](#change-the-repositories-ox-scans). * To connect more Bitbucket accounts to the same organization in the OX platform, see the section [Connect multiple Bitbucket accounts](#connect-multiple-bitbucket-accounts). ## Connect with Identity Provider 1. Verify that the [prerequisites](#prerequisites) are in place. 2. In OX, go to **Connectors** and select **Bitbucket Cloud > IDENTITY PROVIDER**.
3. Select **CONNECT**. OX validates the credentials. 4. In **Confirm access to your account**, select **Grant access**.
5. In **Configure your Bitbucket connector**, select the repos you want OX to scan.
6. Select **SAVE**. 7. In **Configure your Bitbucket credentials**, select **VERIFY CONNECTIVITY**.\ A green checkmark indicates a successful connection. If verification fails, check your credentials and permissions. #### Optional configurations * To change the repositories OX scans and monitors, see the section [Change the repositories OX scans](#change-the-repositories-ox-scans). * To connect more Bitbucket accounts to the same organization in the OX platform, see the section [Connect multiple Bitbucket accounts](#connect-multiple-bitbucket-accounts). ## Connect with user name and password **Step 1: Create password and permissions \[Bitbucket]** For information on creating a password, see the Bitbucket article[ Create an app password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/).\ You can also get the link from the OX UI. Click the link **HELP CONNECTING A PASSWORD**.
1. Verify that the [prerequisites](#prerequisites) are in place. 2. Log in to your Bitbucket Cloud workspace. 3. Go to **Settings > Personal settings > App passwords**. 4. Select **Create app password**. 5. Enter a meaningful label (for example, OX Security Integration). 6. Select the required permissions: * Account: Read and Write * Workspace memberships: Read and Write * Projects: Write and Admin * Repositories: Write and Admin * Pull requests: Read and Write * Issues: Read and Write * Snippets: Read * Webhooks: Read and Write * Pipelines: Read * Runners: Read 7. Select **Create**. 8. Copy and store the app password in a secure location. You cannot view it again. > **Best practice:** Store credentials in a secrets manager and set a reminder to rotate it according to your policy. **Step 2: Connect to OX \[OX]** 1. Go to **Connectors** and select **Bitbucket Cloud > USER NAME AND PASSWORD**.
2. Enter the following parameters.
ParameterDetails
Bitbucket Cloud Host URLhttps://api.bitbucket.org/2.0 (system-generated
User NameYour Bitbucket name
PasswordYour Bitbucket password
Connection NameEnter a meaningful name
3. Select **CONNECT**. OX validates the credentials. 4. In **Configure your Bitbucket connector**, select the repos you want OX to scan.
5. Select **SAVE**. 6. In **Configure your Bitbucket credentials**, select **VERIFY CONNECTIVITY**.\ A green checkmark indicates a successful connection. If verification fails, check your credentials and permissions. #### Optional configurations * To change the repositories OX scans and monitors, see the section [Change the repositories OX scans](#change-the-repositories-ox-scans). * To connect more Bitbucket accounts to the same organization in the OX platform, see the section [Connect multiple Bitbucket accounts](#connect-multiple-bitbucket-accounts). ## Change the repositories OX scans Once you have a connection, you can change the repositories that OX scans and monitors. 1. Use the **Gear** icon at the bottom of the Configuration screen. 2. OX displays the locations or objects that OX scans and monitors. 3. Change the selection as needed. 4. Select **SAVE**.
## Connect multiple Bitbucket accounts You can connect multiple Bitbucket Cloud accounts within the same OX organization. OX secures all accounts under a single organization, and each account can use a different connection method. This setup is useful for large organizations where different teams manage separate Bitbucket Cloud workspaces or require different authentication models. You can combine connection methods—for example: * Use the Bitbucket app for streamlined setup and app-level access. * Use username and password/token for accounts that do not support app installation. * Use an identity provider for centrally managed user access. To add another Bitbucket account, select the connection method and follow the steps in this article.
# Azure Repos Azure Repos is a set of version control tools that you can use to manage your code. Azure Repos provides two types of version control: 1. Git: distributed version control. 2. Team Foundation Version Control (TFVC): centralized version control. Azure Pipelines is a cloud-based solution that automatically builds and tests code projects. Connecting your Azure account allows OX to map and scan your apps for security issues. ### Connection methods
#### Identity Provider 1. In OX, go to Connectors > Source Control > Azure Repos. 2. Open the IDENTITY PROVIDER tab, select **CONNECT,** and follow the instructions on the screen. #### Token 1. To create the token, see the Microsoft documentation. [Create an access token in Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops\&tabs=Windows). 2. Add the permissions listed in the section [Token scopes required](#token-scopes-required). 3. In OX, go to Connectors > Source Control > Azure Repos. 4. Open the TOKEN tab and copy the token into the token field. 5. Select **CONNECT**. #### Service Principal 1. To create a managed identity or application service principal, see the Microsoft documentation [Use service principals and managed identities in Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity). 2. In OX, go to Connectors > Source Control > Azure Repos. 3. Open the SERVICE PRINCIPAL tab and enter the service principal ID (in the Client ID field), the client secret, and the tenant ID to connect. 4. Ensure your host URL follows this format: `https://dev.azure.com/{organizationName}/` #### Connect multiple organizations To connect multiple organizations, use a dedicated Personal Access Token (PAT) for each connection. ### Token scopes required * Auditing - Read Audit Log * Build - Read * Code - Full * Code - Status * Graph - Read and Manage * Identity - Read and Manage * Member Entitlement Management - Read and Write * Project and Team - Read, Write and Manage * Release - Read * Security - Manage * User profile - Read * Wiki - Read * Work items - Read and Write
Once you have verified Azure repos connectivity, you can see all the repositories and can select them for scanning. ### Setting repositories' scope You can use the **Gear** icon to choose the repositories' scope OX will cover. Only repositories chosen here will be covered and scanned. Here you can also decide what will happen by default with newly discovered repositories. # Connecting to Azure #### Getting your Subscription ID 1. Search "subscriptions" in the search bar and click on it.
2. Select your Subscription.
3. Once you click on subscription, select overview on the right-side panel you will get your **Subscription ID**.
#### Get Client ID, Client Secret and Tenant ID 1. Search for "App Registrations" in the search bar and click on it.
2. From the list, select the App which will have Container registry access.
3. Once selected, click on overview on the left side menu and on the right-side panel you will see Client ID and Tenant ID.
4. On the same page on the left side menu click on the only option - Certificates & Secrets. You can create a new secret or use an existing secret value.
# OX Scanners OX-provided scanning technologies appear in the platform as OX connectors and analyze your code, containers, cloud environment, and running applications. Each scanner activates automatically once the required connection is established. When you connect your environment, OX ingests data, runs the appropriate scans, and displays results in the Dashboard, Applications, and Active Issues pages.
OX Security includes the following scanners: * [OX CI/CD Posture](#ox-ci-cd-posture) * [OX Cloud Context](#ox-cloud-context) * [OX Code Security](#ox-code-security) * [OX Container Security](#ox-container-security) * [OX Dynamic App Security](#ox-dynamic-app-security) * [OX Git Posture](#ox-git-posture) * [OX IaC Scan](#ox-iac-scan) * [OX K8s Inspector (Beta)](#ox-k8s-inspector-beta) * [OX Open Source Security](#ox-open-source-security) * [OX SBOM Scan](#ox-sbom-scan) * [OX Secret / PII Scan](#ox-secret-pii-scan) ### How OX Scanners Work Each scanner requires a specific connection or configuration step. Once connected, OX begins scanning automatically and continues scanning on a regular schedule. | Scanner | What You Must Connect First | What the Scanner Does | What Happens If Not Connected | | ----------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | **Code Security** (SAST, IaC Scan, Secrets, SBOM, Open Source Security) | Source control (required) | Scans code for vulnerabilities, secrets, IaC misconfigurations, license risks, dependency issues, and generates SBOMs. | No code-level visibility. | | **Container Security** | Container registry | Scans container images stored in registries for OS/package CVEs, misconfigurations, secrets, and insecure base images. | No image scanning or container posture visibility. | | **Cloud Context** | Cloud account (AWS, GCP, Azure) | Scans cloud resources and configuration, detects misconfigurations, and enriches issues with cloud context. | No cloud posture or resource-level insights. | | **Dynamic App Security (DAST)** | Defined target (URL/endpoint) | Performs dynamic security testing on running applications. | No runtime application testing. | | **Kubernetes Inspector / Runtime Sensor** (Early Availability) | Kubernetes cluster + deployed runtime sensor | Provides runtime visibility into container workloads, image usage, and live execution context. | No runtime metadata or workload-level insights. | ## Scanner Requirements and Recommended Order OX scanners activate automatically once the required connection is in place. The steps below describe the recommended onboarding order and explain what each connection enables. 1. **Connect your source control.**\ This is required for OX to operate.\ Connecting source control activates all code-level scanners, including SAST, Secrets, IaC scanning, SBOM generation, and Open Source Security.\ Without this step, no code scanning or dependency analysis can run. After completing this step, your initial onboarding is essentially complete.\ **All other steps are optional** and depend on your environment, maturity, and security goals. You can configure them later at any time. 2. **Connect container registries** (optional).\ This enables OX to scan Docker/container images stored in registries such as Amazon ECR, Google Artifact Registry, Azure Container Registry, Docker Hub, or GitHub Container Registry.\ Connecting a registry allows OX to automatically discover images and scan them for OS/package CVEs, misconfigurations, secrets, and insecure base images.\ Without this connection, OX cannot analyze your built containers. 3. **Connect cloud accounts** (optional).\ Connecting AWS, GCP, or Azure accounts enables OX to scan cloud resources and configurations, detect misconfigurations, and enrich issues with cloud context.\ Without a cloud connection, cloud posture and cloud-resource visibility are not available. 4. **Set up DAST targets** (optional).\ To run Dynamic Application Security Testing, you must define one or more application targets (URLs or endpoints).\ Once targets are configured, OX performs active testing of running applications.\ Without defined targets, DAST scans will not run. 5. **Deploy the runtime sensor** (advanced / Early Availability).\ Deploying the runtime sensor in your Kubernetes clusters enables runtime-level insights, including workload behavior, image usage, and live execution context.\ Without the sensor, OX cannot collect runtime metadata or correlate issues with live workloads. ## Enable a connector Most OX connectors are enabled by default. If the connector isn’t enabled. **To enable the connector:** 1. Go to the **Connectors** page and locate the relevant connector. Here's an example.\ ![](/files/NrIkWLe0C6YeGl8PWnHo) 2. Click the icon to open the connection screen. 3. Click the toggle to enable the connector or follow the on-screen instructions. ## Disable a connector You can disable a connector in the production environment, but not in the demo environment. Once disconnected, issues and related data are no longer displayed in the UI. **To disable the connector:** 1. Go to the **Connectors** page and locate the relevant connector. 2. Click the icon to open the connection screen. 3. Click the toggle to disable the connector or click **DELETE**. To reconnect, click the toggle or reconnect following the on-screen instructions. ## OX CI/CD Posture The connector analyzes Git and repositories posture to ensure best practices and standards are maintained for code health and organization. The connector is ON by default. ## OX Cloud Context The connector scans cloud environments and configurations to identify security risks, misconfigurations, runtime vulnerabilities, and non-compliance with security best practices. The connector is ON by default. AWS is the cloud provider. For more on cloud-related artifacts, see the article [Cloud BOM](https://docs.ox.security/bom/cloud-bom). ## OX Code Security The connector scans cloud environments and configurations to identify security risks, misconfigurations, runtime vulnerabilities, and non-compliance with security best practices. The connector is ON by default. For supported languages and frameworks, see the [Code Security](/supported-languages-and-frameworks) section in the article [Supported Languages and Frameworks](/supported-languages-and-frameworks). ## OX Container Security The connector scans container images for vulnerabilities, secrets, misconfigurations, and security best practices to ensure a secure containerized environment. The connector is ON by default. ## OX Dynamic App Security The connector scans real-time testing of live applications to uncover vulnerabilities in their running environments. It simulates real attack scenarios to identify what truly matters, beyond static code analysis. The connector is ON by default. ## OX Git Posture The connector analyzes Git and repositories posture to ensure best practices and standards are maintained for code health and organization. The connector is ON by default. ## OX IaC Scan The connector scans source code to detect infrastructure-as-code configurations for security best practices and potential misconfigurations that could lead to vulnerabilities. The connector is ON by default. For supported languages and frameworks, see the[ Infrastructure as Code Support](/supported-languages-and-frameworks) section in the article[ Supported Languages and Frameworks](/supported-languages-and-frameworks). ## OX K8s Inspector (Beta) The connector runs in your Kubernetes cluster and collects runtime metadata and configuration details. It securely sends this data to the OX platform, providing visibility into active workloads, identifying public images in use, and enriching vulnerability context. The connector is OFF by default. To connect, see the article [OX K8s Inspector](https://docs.ox.security/making-connections/ox-inspector). For supported languages and frameworks, see the [Infrastructure as Code Support](/supported-languages-and-frameworks) section in the article [Supported Languages and Frameworks](/supported-languages-and-frameworks). ## OX Open Source Security The connector scans source code to detect vulnerable open-source components, libraries, and Docker files that could be exposed. The connector is ON by default. For supported languages and frameworks, see the section ​[Open Source Security & SBOM](https://docs.ox.security/get-started/supported-languages-and-frameworks#sca-and-sbom-support) in the article [Supported Languages and Frameworks](https://docs.ox.security/get-started/supported-languages-and-frameworks). ## OX SBOM Scan The connector scans source code and containers to generate a detailed Software Bill Of Materials with all components, libraries, and tools used in the software, along with their versions and dependencies, for transparency and compliance. The connector is ON by default. For supported languages and frameworks, see the section ​[Open Source Security & SBOM](https://docs.ox.security/get-started/supported-languages-and-frameworks#sca-and-sbom-support) in the article [Supported Languages and Frameworks](https://docs.ox.security/get-started/supported-languages-and-frameworks). You might also want to check these articles: [Malicious Dependencies](https://docs.ox.security/policies/malicious-dependencies) and [SBOM](https://docs.ox.security/bom/sbom). ## OX Secret / PII Scan The connector scans source code to detect and alert on embedded secrets, such as passwords or API keys, and personally identifiable information (PII) that could be exposed. The connector is ON by default. # Review Scan Results After you connect your source control system, OX runs an initial scan. Review the results to confirm that OX detected the expected applications and added new issues for your repositories. * [**Dashboard:**](/get-started/onboarding-to-ox/review-scan-results/dashboard) Go to **Dashboard** to see an overview of detected applications and issues from the first scan. * [**Runtime Dashboard:**](/get-started/onboarding-to-ox/review-scan-results/runtime-dashboard) Go to **Runtime Dashboard** to monitor the security posture of your running workloads, including cluster health, container image risks, and open source vulnerability prioritization. * [**Cloud Security Dashboard:**](/ox-cloud/cloud-security/cloud-security-dashboard) Go to **Cloud Security Dashboard** to review cloud misconfigurations, exposed secrets and sensitive data, compliance posture, and risk distribution across your cloud projects. * Cloud Security Dashboard: * [**Applications:**](broken://pages/ttzpvAi1mvYbDMySi6Eu) Go to **Applications** to verify that OX identified the applications you expected. * [**Active Issues:**](/scan-and-analyze-with-ox/analyzing-scan-results/issues) Go to **Issues > Active Issues** to review the issues created during the first scan. * [**Reports:**](/generate-reports/reporting) Go to **Reports** to view scan results. # Dashboard The OX dashboard provides a system-wide snapshot of your security posture. It brings together issue status, application security coverage, asset inventory, and trends in a single view so you can quickly understand what requires attention. OX focuses on protecting what really matters by reducing noise and highlighting real risk. The dashboard helps you: * See the full impact of an issue across tools and environments through aggregation, by grouping related findings into a single issue. * Focus remediation efforts where they matter most through prioritization, by ranking issues based on runtime context, exposure, and business impact. * Improve visibility across your delivery pipeline and runtime environment, by showing security coverage from source control through deployment. * Track progress over time, by monitoring severity and status trends as issues move through remediation. This page describes the standard dashboard that opens by default when you log in. You can later replace this view with [a custom dashboard based on a report](/get-started/onboarding-to-ox/review-scan-results/custom-dashboard-views) that better matches your daily workflow.
## Issues status and prioritization This section summarizes open issues by severity and shows how findings move through OX processing, from raw scanner output to actionable, prioritized issues.
ElementDescription
Severity SummaryCards that show the number of open issues for each severity level (Apocalypse, Critical, High, Medium) and the current MTTR for each level.
Original AlertsThe total number of findings as reported by connected scanners and tools, before OX applies correlation or prioritization.
OX AggregationA consolidated view of related findings grouped into a single issue based on shared attributes such as asset, component, vulnerability type, and location.
OX PrioritizationA ranked view of aggregated issues based on severity, runtime context, exposure, and business impact.
## AppSec Data Fabric This section shows coverage across the main stages of your software delivery and runtime environment. Each tile represents a domain and indicates whether posture and scan data are available.
| Domain | What it shows | Why it matters | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | **Source Control** | Posture and scan coverage for connected repositories, including code, secrets and PII, open source, SBOM, and Infrastructure as Code. | Confirms that development assets and dependencies are being monitored. | | **CI/CD** | Pipeline posture and scan status for connected CI/CD systems. | Confirms that security checks run during build and deployment. | | **Registry** | Container and artifact security coverage for connected registries. | Confirms that images and artifacts are scanned before deployment. | | **Cloud Deployment** | Runtime and cloud context, including API security, artifact integrity, and cloud exposure. | Shows risk in deployed and running workloads. | ## Assets This section provides a count of key asset types managed by OX.
| Asset type | Description | | ----------------------------------- | ------------------------------------------------------------------------------------ | | **Applications** | Logical groupings of repositories, services, and workloads managed as a single unit. | | **Pipeline protected repositories** | Repositories with CI/CD protection and scan enforcement enabled. | | **Libraries** | Open source and third-party dependencies identified across repositories and images. | | **APIs** | Discovered or defined application programming interfaces. | | **Artifacts** | Build outputs such as packages and images stored in registries. | | **Cloud assets** | Cloud resources discovered across connected accounts. | | **SaaS** | Connected software-as-a-service applications. | ## Issue severity trend over time This chart shows how the number of issues changes over time by severity.
| Aspect | Description | | ------------------ | ----------------------------------------------------------------- | | **Time range** | The period displayed on the horizontal axis. | | **Severity bands** | Color-coded areas that represent issue counts per severity level. | | **Data points** | Snapshots of issue counts at each point in time. | ## Issue status trend over time This chart shows how issue states change over time, such as open, resolved, or suppressed.
| Aspect | Description | | --------------------- | ---------------------------------------------------------------- | | **Time range** | The period displayed on the horizontal axis. | | **Status categories** | Issue states tracked over time. | | **Data points** | Snapshots of issue counts for each status at each point in time. | ## Last scan indicator The upper-right corner of the dashboard shows the time of the most recent scan.
| Field | Description | | ------------- | ------------------------------------------------------------------------- | | **Last scan** | The timestamp of the most recent completed scan across connected sources. | # Custom Dashboard Views You can personalize your [Dashboard ](/get-started/onboarding-to-ox/review-scan-results/dashboard)by adding additional dashboard views based on existing reports. A dashboard view is a personal configuration that lets you switch between report-based views and optionally apply one as your default dashboard. Custom dashboard views are user-specific. Each user manages their own views and default dashboard, and these settings do not affect other users in the organization. ## **Add/remove a report as a dashboard view** You can add any existing report as an additional dashboard view, without changing the standard dashboard. **To add a report as a dashboard view:** 1. Go to **Reports**. 2. Open the report you want to add as a dashboard view. 3. In the upper-right corner of the report, select the three-dots menu.
4. Select **Add as Dashboard view**. The report is now available as an additional dashboard view. Adding a dashboard view does not change your default dashboard. **To remove a dashboard view:** 1. Open the report. 2. Select the three-dots menu.
3. Select **Remove from Dashboard**. ## **View and switch between dashboard views** After you add one or more dashboard views, you can switch between them directly from the Dashboard page. You do not need to reopen the report itself. **To switch between dashboard views:** 1. Go to **Dashboard**. 2. Select the arrow next to the dashboard title.
3. Select the dashboard view you want to see. The selected dashboard view opens immediately. Dashboard views are not shown automatically. You must explicitly select them from the list. ## **Set a dashboard view as your default** You can optionally apply one of your dashboard views as your default dashboard. This replaces the standard dashboard for you only. Setting a default dashboard does not remove the standard dashboard and does not affect other users. **To set a dashboard view as the default:** 1. Go to **Dashboard**. 2. Open the dashboard views list. 3. Select the dashboard view you want to apply. 4. Select **Apply as default**. Once applied, this dashboard view opens automatically when you go to the Dashboard page. # Runtime Dashboard The Runtime dashboard provides visibility into your [runtime environment](/ox-cloud/ox-runtime-sensor), including cluster health, open source risk exposure, and container image usage. It helps you understand the security posture of your running workloads and which images are high-risk and what their sources are.
Use this dashboard to: * Focus on exploitable risks. * Prioritize high-risk container images for remediation. * Monitor usage of base and public images across environments. * Validate that images are sourced from trusted registries. ### Connected Clusters Displays OX Runtime Sensors on Kubernetes clusters. Clicking **View Health Center** opens the Runtime Sensor Health Center, a dedicated dashboard that provides full visibility into the health and status of all your Runtime Sensors.
* **Connected Clusters**: All monitored clusters and their current health status at a glance. * **Connected Sensors Over Time**: A trend graph showing how many Runtime Sensors have been connected at any given point in time. This view helps you detect unexpected drops, for example, if you normally have 60 Runtime Sensors connected and the count drops to 45, you can identify and investigate the shift immediately. * **Sensor Health:** The list of all the monitored clusters. #### Cluster Details Clicking on a **Cluster Name** within the Health Center opens a detailed view for that specific cluster. The view is divided into two areas, Cluster Info and Nodes. This per-cluster, per-node breakdown supports a range of use cases, from routine health monitoring to audit and compliance scenarios where you need to demonstrate sensor availability and resource consumption over time.
**Cluster Info** is a summary of the cluster-level details. | Field | Description | | --------------- | ---------------------------------------------------------- | | Cluster Name | The name of the cluster | | Cloud Type | The cloud provider the cluster runs on (for example, AWS) | | Cloud Account | The cloud account ID associated with the cluster | | Sensor Version | The version of the Runtime Sensor currently deployed | | Cluster Status | Overall health status of the cluster (Healthy / Unhealthy) | | Healthy Nodes | Number of nodes currently in a healthy state | | Unhealthy Nodes | Number of nodes currently in an unhealthy state | **Nodes** table is a per-node breakdown of all nodes in the cluster. | Column | Description | | ------------- | ------------------------------------------------------------------- | | Node Name | The name of the node | | Last Activity | When the node last reported activity, including the exact timestamp | | Sensor Memory | Memory currently consumed by the Runtime Sensor on that node | | Sensor CPU | CPU currently consumed by the Runtime Sensor on that node | | Sensor Status | Health status of the sensor on that node (for example, Healthy) | ## Open Source Issues Funnel Visualizes how open source risks are distributed and prioritized. This funnel helps you focus on the issues most likely to be exploited in runtime. | Metric | Description | | -------------------------------------- | -------------------------------------------------------------------------------------------- | | All issues | Total number of detected open source issues | | Packages loaded | Issues in packages that are actively used in runtime | | Known exploit | Issues with publicly known exploits | | EPSS/AI-simulation prioritized | Issues with a higher likelihood of exploitation based on scoring and simulation | | KEV / malicious dependency prioritized | Issues linked to known exploited vulnerabilities or malicious dependencies loaded in runtime | ## Top Risk Images Lists container images with the highest risk across your clusters. Use this table to prioritize remediation for the most critical runtime exposures. | Column | Description | | ----------- | ------------------------------------------------------------------- | | Image | Name of the container image | | Cluster | Cluster where the image is running | | Context | Indicators such as exposure, privilege level, or runtime conditions | | Image age | Time since the image was built | | Application | Associated registry or repository | | Severity | Highest detected risk level for the image | ## Most Used Base Images Shows the base images most frequently used across your environment. * Helps identify standardization patterns * Highlights widely used images that may introduce systemic risk Focus on securing commonly used base images to reduce overall exposure. ### Most Used Public Images Displays the most frequently used public container images. * Includes images pulled from public registries * Indicates how widely each image is used Public images increase supply chain risk, so this view helps identify where to apply stricter controls. ## Image Registry Source Breaks down image usage by registry source. * Amazon ECR * Docker Hub * Other registries Use this to understand where your images originate and assess trust levels for each source. # Planning Next Steps After reviewing your first scan results, plan the next steps to tailor OX to your environment and workflow: * **Connect Container Registries and Cloud Accounts:** Add container registries and cloud accounts if they are relevant to your environment. This is optional and depends on the type of applications you manage. * [**Connect Your Ticketing and Messaging Systems:**](/ticketing-and-messaging/about-messaging-and-ticketing-in-ox) Connect systems such as Jira to streamline issue creation and assignment from OX. * [**Connect CI/CD Pipelines:**](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines) Integrate your pipelines to scan, build artifacts, and enforce security checks during development. This step is more advanced and not required for your first scan. * [**Configure Workflows:**](/automate-with-ox-workflows/ox-automations) Adjust or create workflows to define how issues should be handled, routed, or automated across your teams. * [**Enable Runtime Visibility:**](/ox-cloud/ox-runtime-sensor) Connect your runtime environment to help OX understand which components are actually used in production. * [**Fine-tune Policies:**](/ox-policies/policies) Review the built-in policies, such as License Policy and other security policies, and confirm they reflect the rules you want to enforce in your organization. # Scanning Methods OX Security continuously monitors your development and runtime environments to identify and prioritize security issues across the software supply chain. OX connects to your source control, CI/CD, artifact registries, cloud environments, and external testing tools to collect findings and context. Each scan enriches OX’s unified graph, so you see one consistent view of issues, owners, impact, and required actions. OX supports multiple scan entry points. Repository and registry connectors keep your data in sync so new commits, pull requests, images, and packages are analyzed without manual effort. Pipeline jobs validate builds before they ship and can block based on your policy. The IDE extension analyzes local changes to help you fix issues before they reach the repo. You can also import results and SBOMs from third-party scanners, or trigger on-demand scans by API when you need a targeted check. The OX scanning engine supports multiple scanning modes, enabling flexible and comprehensive coverage tailored to your workflow and infrastructure. This section covers the available scanning methods in OX: * [**Regular Scans**:](/get-started/onboarding-to-ox/ox-connectors) Automatically triggered by default across all connected assets, these scans ensure ongoing security visibility. * [**Selected Repositories Scans**:](/scan-and-analyze-with-ox/scanning/scanning-selected-repositories) Target specific repositories to reduce scan scope and optimize performance when full coverage is not needed. * [**Pipeline Scans**:](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines) Integrated directly into your CI/CD pipelines to detect vulnerabilities immediately after build, before images are deployed or pushed to registries. * [**IDE Scans:**](/scan-and-analyze-with-ox/scanning/ox-ide-integrations/ox-ide-extension) Run in your IDE with the OX IDE extension to analyze modified files as you code, flag issues inline, and suggest fixes including AI-based remediation for supported languages, preventing new issues before commit. * [**Multi-branch Scans:**](/scan-and-analyze-with-ox/scanning/multi-branch-support) Extend coverage beyond the default branch to scan multiple branches in parallel (for example, development, staging, production) and maintain visibility across release lines. # Scanning Code and Artifacts in CI/CD Pipelines OX Security integrates with CI/CD pipelines to scan code and artifacts changes as they are introduced. This enables early detection of vulnerabilities and misconfigurations during development, before code is merged or deployed. Pipeline scanning is one of several targeted scanning methods supported by OX and is designed to complement the full scan. While a full scan provides broad visibility across all repositories on a scheduled basis, pipeline scans focus on a single repository and analyze only the changes introduced in a specific push or pull request. Benefits of pipeline scans: * **Speed**: Pipeline scans are faster because they only analyze modified files. * **Immediate feedback**: Scans run as soon as code is pushed or a pull request is opened. * **Focused results**: Helps developers quickly identify and resolve newly introduced issues like secrets or vulnerabilities. ### How pipeline scanning works in OX A pipeline scan runs automatically when triggered by version control events such as pushes or pull requests. The scan analyzes the affected files or artifacts and reports any security findings. This allows teams to block risky builds and enforce secure coding practices early in the development lifecycle. OX Security supports the following types of pipeline scans: * **Pull request event scans:** Scans only the files that were modified in the source branch before it is merged into the target branch. * **Push event scans:** Scans only the files that were modified in commits pushed to the source branch after the last successful pipeline scan on that branch. ## Setting up pipeline scans 1. Before setting up pipeline scans, make sure the repository went through a full scan. > **Note:**\ > Pipeline scans can run even if a full scan has not been completed. However, running a full scan first is recommended for accurate and complete results, because pipeline scans rely on the application and repository data collected during the full scan. 2. Go to the **Applications** page.
3. Select a repository for which you want to configure pipeline scanning and click the **Pipeline Settings** icon at the top. 4. In the [Pipeline Settings page, review the settings that define how the scan behaves](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/pipeline-scan-settings). > **Note:** OX Security recommends using the default settings. 5. Configure the [trigger mechanism in your source control platform](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms). 6. Go to the [**Pipeline Workflows** page to define how OX reacts to findings](/automate-with-ox-workflows/pipeline-workflows). 7. Validate the integration.\ Push a code change or open a pull request to verify that the pipeline scan runs and reacts as expected. 8. [View and analyze scan results.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/understanding-pipeline-scan-results) # Pipeline Scan Settings When configuring [pipeline scans](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines), you need to define how the scan behaves. You can configure which branches trigger scans, whether to respond to push or pull request events, and how to handle timeouts or scan failures. For example, you might choose to react only to pull requests, which typically represent changes intended for merging into protected branches. OX Security recommends starting with the default configuration and adjusting it based on your workflow needs.
SettingDescriptionRecommendation
TimeoutMaximum time a pipeline scan is allowed to run. If exceeded, the scan is terminated. Helps prevent stuck or long-running jobs.Use default at first. Tune based on observed performance.
Behavior on Error/TimeoutDefines whether the pipeline should be blocked if the scan fails or times out. Failure may not indicate an issue, could be a timeout or data fetch problem.Start with non-blocking (alert). Move to blocking once pipelines are stable.
Scan Performance ModeControls the depth of repository analysis performed during the pipeline scan, as follows:
- Detailed scan: Runs the scan with dependency graph generation and also collects Git repository information (Git history and related metadata from the .git folder during clone).
This mode enables additional context such as information derived from commit history (for example, author-related metadata) and other details based on Git history.
- Regular scan: Runs the scan with dependency graph generation.
This mode provides dependency-graph-based context, but does not collect Git history information.
- Fast scan: Runs the scan without generating the dependency graph.

Available only using feature flag. Use only if needed and enabled for your account.

Start with Regular.

Use Fast when you need shorter scan times and can work without dependency graph context. The time saved depends on how long dependency graph generation takes for your repositories.

Use Detailed when you need Git-history-based context. It can be around 2x slower than Regular depending on the repository.

# Integrating Source Control Platforms OX supports App, Webhook, and Direct CI/CD methods for integrating with your source control system. These methods are not mutually exclusive; you can combine them. Required scopes and permissions for each source control integration are described in their respective configuration guides. #### Comparison of Integration Methods | Method | Pros | Considerations | | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [GitHub App and Bitbucket App](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/app-pipeline-integration) | Minimal setup per repo, UI-based control | Available only for supported platforms (GitHub, Bitbucket). | | [Direct CI/CD](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration) | Full customization per repo |
  • Requires configuring and maintaining YAML file in each repository.
  • Setup can be more complex and requires familiarity with YAML syntax.
| | [Webhook](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/webhooks-pipeline-integration) | Centralized setup, easy to apply at scale | Less flexible than per-repo YAML. | OX integrates with the following source control platforms: * **App** * [GitHub App](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/app-pipeline-integration/github-app) * [Bitbucket App](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/app-pipeline-integration/bitbucket-app) * **Webhooks** * [GitLab Webhooks](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/webhooks-pipeline-integration/gitlab-webhooks) * **Direct CI/CD** * [GitHub Actions](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/github-actions) * [GitLab CI/CD](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/gitlab-ci-cd) * [Bitbucket Pipelines](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/bitbucket-pipelines) * [Jenkins](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/jenkins) * [Azure Pipelines and Azure DevOps](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/azure-pipelines-and-azure-devops) ## Configuring SaaS and On-Prem source control platforms All source control systems operate both as Software as a Service (SaaS) and on-premises solutions, with the exception of Gerrit, which only functions as an on-prem solution. To configure your source control system on-premises, it must meet the following requirements: * Whitelist IPs for OX connection. * OX\_HOST\_URL: * For OX Broker, you need to whitelist outgoing traffic to OX IPs. # App Pipeline Integration The App method provides a seamless way to trigger pipeline scans without modifying the pipeline code. After installing and connecting a supported app, such as GitHub App or Bitbucket App, you can manage scan behavior using the OX platform. This method is ideal for teams that want centralized control over scans without editing each repository’s configuration. It also enables advanced capabilities such as workflow assignment and selective scanning, defined per application inside the OX platform. You can view or edit scan behavior under each application’s Pipeline Settings page once the integration is active. #### App Integration in Pipeline Scanning The App Integration method optimizes pipeline scanning by providing automation and centralized management. Once an app like GitHub or Bitbucket is installed and connected, it leverages OX platform features to streamline scanning processes. **Key Advantages:** * **Centralized Control**: Manage all scan settings through a unified interface without touching source code. * **Advanced Customization**: Assign workflows and select specific scans tailored to each application's requirements. * **Scalability**: Easily expand the scanning process across multiple applications or repositories with minimal setup. # GitHub App OX Security supports pipeline scanning using the GitHub App, which uses GitHub webhooks to trigger scans. This approach does not require modifying CI/CD configurations or adding the OX CLI to pipeline jobs. Instead, OX listens for GitHub events and initiates scans automatically. OX detects pull requests and push events directly from GitHub. Based on the event, OX identifies the modified files and performs a scan. The scan runs outside your pipeline and reports results in the OX UI. No CLI or container is needed inside your GitHub workflow. #### GitHub Merge Queue support > **Note:** > > * This capability is currently in Early Access (EA) and is not generally available. To request access, please contact OX technical support. GitHub Merge Queue is a GitHub capability that validates pull requests in a temporary merge queue before they are merged into a protected branch. Instead of merging pull requests individually, GitHub creates a temporary combined branch and runs the required checks against that state. OX can scan Merge Queue events when using GitHub App pipeline integration. Merge Queue scans use the same pipeline configuration that is defined for pull request events. No additional configuration is required in OX. Any policies, checks, and blocking behavior configured for pull requests are automatically applied to Merge Queue runs. If a blocking OX policy fails, GitHub prevents the queued changes from being merged until the issues are resolved. After the capability is enabled, OX automatically analyzes Merge Queue runs and displays the results on the [Pipeline Summary](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/understanding-pipeline-scan-results/pipeline-summary) page. ## Prerequisites * The GitHub App must be installed in your GitHub organization. * [You must grant the app access to the repositories you want to scan.](/get-started/onboarding-to-ox/source-control/github) ## Required Configuration OX initiates scans using webhook data from GitHub. You do not need to add variables or modify settings. You just need to [make sure that webhooks are enabled.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/webhooks-pipeline-integration) ## Block pull request merges based on OX scan results You can configure GitHub branch protection rules to prevent pull requests from being merged when OX detects issues that match your blocking policies. When OX scans a pull request, it reports the scan result to GitHub as the **ox-security/scan** status check. If the scan finds blocking issues, the status check fails, and GitHub can prevent the merge. **To require OX scans before merging:** 1. In GitHub, open the repository and select **Settings** > **Branches**.
2. Create a new branch protection rule or edit an existing rule for the target branch (for example, `main`). 3. Under **Protect matching branches**, select **Require status checks to pass before merging**. 4. (Optional) Select **Require branches to be up to date before merging**. 5. In the required status checks list, add **ox-security/scan**. 6. Save the rule. After the rule is configured, pull requests cannot be merged until the **ox-security/scan** check completes successfully. If OX finds issues that match your blocking policies, the check fails and GitHub blocks the merge until the issues are resolved. > **Note** > > The `ox-security/scan` status check appears after OX has processed pull requests for the repository. # Bitbucket App OX Security supports integration with Bitbucket Cloud using the OX Bitbucket App. This integration enables automatic pipeline scans triggered by events such as push and pull requests, without modifying your CI/CD pipeline configuration. OX listens for push and pull request events from Bitbucket Cloud. When an event is detected, OX identifies the modified files and triggers a pipeline scan for the specific repository. Scans run outside the Bitbucket pipeline and results are [displayed in the OX platform](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/understanding-pipeline-scan-results). ## Prerequisites * Bitbucket Cloud account * Admin access to your Bitbucket workspace * The OX Bitbucket App is installed and authorized for your repositories ## Required Configuration OX initiates scans using webhook data from BitBucket. You do not need to add variables or modify settings. You just need to [make sure that webhooks are enabled.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/webhooks-pipeline-integration) **To connect to Bitbucket app:** 1. Go to the OX platform and navigate to **Connectors > Source Control**. 2. Select **Bitbucket App** and click **Connect**. You are redirected to Bitbucket. 3. Approve the OX Security app. 4. Select the repositories you want to monitor with OX. When connected, OX automatically receives webhook events and performs scans on changes. ### Block pull request merges based on OX scan results You can configure Bitbucket branch restrictions to prevent pull requests from being merged when OX detects issues that match your blocking policies. OX reports scan results to Bitbucket as build results. When a scan finds issues that match your blocking policies, the build fails, and Bitbucket prevents the pull request from being merged. To require successful OX scans before merging: 1. In Bitbucket, open the repository and select **Repository settings**. 2. Select **Branch restrictions**.
3. Select **Add a branch restriction** or edit an existing restriction for the target branch.
4. On the **Merge settings** tab, select **Minimum number of successful builds for the last commit with no failed builds and no in progress builds**. 5. Set the value to **1**. 6. Select **Save**. After the restriction is configured, pull requests cannot be merged until all required builds complete successfully. If OX finds issues that match your blocking policies, the build fails and Bitbucket blocks the merge until the issues are resolved. # Webhooks Pipeline Integration You can configure source control systems to notify OX using a webhook on relevant events. Webhooks can be set up once for each group or project. This method is useful for customers managing many repositories or using UI-driven CI/CD. Webhook settings control how OX interacts with your source control system to report scan statuses and trigger scans automatically. These settings define whether OX sends status updates, such as scan started/finished, back to the platform, and which branch events trigger scans. **To set webhooks:** 1. Go to the **Applications** page and select the applications in which you want to apply pipeline scan. 2. Click the **Pipeline Settings icon** at the top. 3. In the **Webhooks** section of the **Pipelines** dialog, perform webhook configuration by source control platform, as follows: * For GitLab Webhooks integration, enable **GitLab Commit Status and Merge Request Notes Reporting**.
* For GitHub App integration, enable **GitHub Checks**. > **Note:** [Merge Queue support](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/app-pipeline-integration/github-app#github-merge-queue-support) is currently available as an Early Availability capability. Merge Queue events inherit the Pull Request configuration. Any policies, checks, and blocking behavior configured for pull requests are automatically applied to Merge Queue runs. To enable this capability, contact OX Support.
* For Bitbucket App integration, enable **Bitbucket Code Insights and Build Status Reporting**.
SettingDescription
ChecksEnable to publish pipeline scan results in the source control platform's native code review interface, allowing reviewers to see the scan status directly from the pull request or merge request.
Post Scan SummaryEnable posting a summary of each pipeline scan as a comment on the pull request or merge request. The summary includes the source and target branches, scan ID, total issues, blocking issues, scan status, and a link to the scan results in OX.
Show SuccessEnable to post a scan summary even when no issues are found. When disabled, OX posts summaries only when the scan identifies issues.
Example of the post scan summary in the source control system:
4. Define which branches and events to monitor. You can use default options (e.g., `main`, `protected`) or patterns like `release-*`. | Setting | Description | Recommendation | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Branch Event Types to Scan | Specifies the types of branch events (Push, Pull Request) that trigger scans. | Choose Pull Request for protected/default branches. Customize for others as needed. | | Branch Filters (Name Patterns) | Define naming patterns for branches to include in scan events. You can use wildcard (`*`) to include multiple branches with similar naming. | Use this to scan custom branch types, e.g., `release-*` or `feature-*`. | 5. Select **SAVE**. # GitLab Webhooks OX Security integrates with GitLab webhooks to enable commit status updates and merge request comments after scans. > **Note:** GitLab webhook integrations do not support IDP-based credentials (such as OAuth or SSO). You must use personal or group access tokens. ### Step 1: Configure webhooks in GitLab After configuring your connector in the OX platform, create a webhook in GitLab. You can set it at the group level or project level. | Field | Value | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **URL** | `https://api.cloud.ox.security/api/gitlab/webhooks` | | **Secret token** | [Your OX Security integration key.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/creating-ci-cd-integration-key) | | **Triggers** | Enable **Merge request events** and **Push events**, depending on your needs. | ### Step 2: [Enable scanning with webhooks in OX Security](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/webhooks-pipeline-integration) **For example:** * **Commit status:** Appears as an external stage check in GitLab.
* **Merge request note:** A comment with scan details is added to the merge request.
# Direct CI/CD Integration The Direct Source Control integration allows teams to define their configurations using a YAML file directly within their repositories. This method provides the flexibility to customize the integration settings and behavior for each project. Most CI systems (e.g., GitHub Actions, GitLab CI) allow defining pipelines using YAML files. You can add OX scan steps to these files directly in the repository. * Example: Add a scan command to `.gitlab-ci.yml` or `.github/workflows/scan.yml` * You can specify flags, severity filters, and behavior per pipeline job. This method provides granular control over integration settings and allows version-controlled configuration management, but requires configuration for each repository and might be more complex in configuration and maintenance than other methods. You can use this method in the following systems: * [GitHub Actions](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/github-actions) * [GitLab CI/CD](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/gitlab-ci-cd) * [Bitbucket Pipelines](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/bitbucket-pipelines) * [Jenkins](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/jenkins) * [Azure Pipelines and Azure DevOps](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/azure-pipelines-and-azure-devops) * [Generic CI](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/generic-ci) # Creating CI/CD Integration Key To integrate with CI/CD platforms, you need to create integration keys. **To create a new integration key:** 1. From the left pane of the **OX dashboard**, select **Settings > API Key Settings**. 2. In the **API Key Settings** window, select **CREATE API KEY**.
3. In the **Create API Key** box set the following and select **CREATE**: * **API Key Name:** Add a meaningful name that is easy to identify. It is good practice to include the key's intended purpose in the name. * **API Key Type:** Select **CI/CD Integration**. * **Expiration Date:** Until when you can use this key.
4. Copy the **API Key Secret** to be used when connecting to APIs. Save the key in a safe location. This is the only time when you can see and copy the actual key. 5. Select **CLOSE**. The new key appears in the **API Key Settings** page. # GitHub Actions OX Security integrates with GitHub Actions to detect vulnerabilities in your code or container images during CI/CD builds. The OX GitHub Action runs a full security scan, covering secrets, SAST, SCA, IaC, and more, on every push or pull request, and evaluates the results against your defined security policies. If a blocking issue is detected, the workflow will fail unless overridden. You can configure global or repository-specific policies in the OX platform to determine enforcement behavior. This integration is highly customizable and supports any event trigger supported by GitHub Actions. > When using pull request or push triggers in GitHub Actions, scans run automatically without needing manual webhook setup. ## Prerequisites * A **GitHub repository** connected to your OX application. * A valid **OX Security API key** stored as `OX_API_KEY` in your repository secrets. ## Required environment variables | Input | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ox_api_key` | [The OX Security API key.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/creating-ci-cd-integration-key) | ## Optional environment variables | Input | Description | | ---------------------- | ---------------------------------------------------------------------------- | | `ox_override_blocking` | Set to `true` to override blocking issues and allow the workflow to succeed. | | `ox_timeout` | Maximum scan duration in minutes. Defaults to `20`. | | `ox_fail_on_timeout` | Set to `true` to fail the job if the scan times out. | | `ox_fail_on_error` | Set to `true` to fail the job when network or system errors occur. | ## Advanced environment variables | Input | Description | | --------------------------- | --------------------------------------------------------------------------------------------------- | | `ox_disable_ssl_validation` | Set to `true` to disable SSL certificate validation (useful for self-signed or internal endpoints). | ## Integration Example (`.github/workflows/scan.yml`) ```yaml name: Security Scan on: push: branches: [main] pull_request: branches: [main] jobs: scan: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v3 - name: OX Security Scan uses: oxsecurity/ox-security-scan@main with: ox_api_key: ${{ secrets.OX_API_KEY }} # ox_override_blocking: false # ox_timeout: 20 # ox_fail_on_timeout: false # ox_fail_on_error: false # ox_disable_ssl_validation: false ``` # GitLab CI/CD OX Security integrates with GitLab CI/CD pipelines to detect vulnerabilities in Docker-based jobs. To run scans on merge requests before they are merged, you must enable `merge request pipelines` in your GitLab CI/CD settings. ### Prerequisites * **Docker support:** Your GitLab runners must support Docker and be able to run Docker-based jobs. ### Required environment variables | Variable | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OX_API_KEY` | [The OX Security API key.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/creating-ci-cd-integration-key) | ### Optional environment variables | Variable | Description | | ---------------------- | ------------------------------------------------------------------ | | `OX_OVERRIDE_BLOCKING` | Set to `true` to override job failure caused by blocking issues. | | `OX_TIMEOUT` | Maximum duration of the scan, in minutes. | | `OX_FAIL_ON_TIMEOUT` | Set to `true` to fail the job if a scan times out. | | `OX_FAIL_ON_ERROR` | Set to `true` to fail the job if a system or network error occurs. | ### Advanced environment variables | Variable | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------ | | `OX_DISABLE_SSL_VALIDATION` | Set to `true` to disable SSL certificate validation for self-signed certificates in on-premise environments. | ### Integration example (`.gitlab-ci.yml`) ```yaml stages: - test ox_security_scan: stage: test image: oxsecurity/ox-block-mode:latest variables: OX_API_KEY: $OX_API_KEY # OX_OVERRIDE_BLOCKING: false # OX_TIMEOUT: 20 # OX_FAIL_ON_TIMEOUT: false # OX_FAIL_ON_ERROR: false script: - ox-block-mode allow_failure: false ``` # Bitbucket Pipelines OX Security supports integration with Bitbucket Pipelines to scan code changes during development. This allows you to detect security issues before the code is merged or deployed. ## Prerequisites * Bitbucket Pipelines must support running Docker image–based pipes. * The `OX_BITBUCKET_FULL_COMMIT` variable must be set explicitly due to a known Bitbucket issue that causes `BITBUCKET_COMMIT` to be shortened. Without this, scans may fail. ## Required environment variables | Variable | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OX_API_KEY` | [Your OX Security API key.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/creating-ci-cd-integration-key) | ## Optional environment variables | Variable | Description | | -------------------------- | ----------------------------------------------------------------------------- | | `OX_BITBUCKET_FULL_COMMIT` | Full commit SHA. Required due to Bitbucket’s short SHA issue. | | `OX_OVERRIDE_BLOCKING` | Set to `true` to allow the job to continue even if blocking issues are found. | | `OX_TIMEOUT` | Scan timeout (in minutes). | | `OX_FAIL_ON_TIMEOUT` | Set to `true` to fail the job if the scan times out. | | `OX_FAIL_ON_ERROR` | Set to `true` to fail the job if an infrastructure or network error occurs. | ## Advanced environment variables | Variable | Description | | --------------------------- | --------------------------------------------------------------------------- | | `OX_DISABLE_SSL_VALIDATION` | Disables SSL certificate validation for self-signed certs (on-premise use). | ### Integration Example (`bitbucket-pipelines.yml`) ```yaml image: node:18 pipelines: pull-requests: main: - step: name: OX script: - export OX_BITBUCKET_FULL_COMMIT=$(git rev-parse --verify $BITBUCKET_COMMIT 2>/dev/null) - pipe: docker://oxsecurity/ox-block-mode variables: OX_API_KEY: $OX_API_KEY OX_BITBUCKET_FULL_COMMIT: $OX_BITBUCKET_FULL_COMMIT # OX_OVERRIDE_BLOCKING: false # OX_TIMEOUT: 20 # OX_FAIL_ON_TIMEOUT: false # OX_FAIL_ON_ERROR: false ``` > **Note:** The `OX_BITBUCKET_FULL_COMMIT` variable is required for proper scan functionality. Bitbucket's default `BITBUCKET_COMMIT` may return a short SHA and cause issues in scan context detection. # Jenkins OX Security integrates with Jenkins to scan Docker-based builds for security issues. To scan pull requests before they are merged, you must configure Jenkins to provide source and target branch information in the pipeline. ### Prerequisites * **Docker support:** Jenkins must be able to run Docker containers. * **Git information:** Jenkins must use the Git plugin or be manually configured to provide commit and branch details. ### Required environment variables | Variable | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OX_API_KEY` | [The OX Security integration key.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/creating-ci-cd-integration-key) | | `OX_HOST_URL` | The OX platform URL (only if using an on-premise installation). | | `GIT_URL` | The repository URL. Provided by the Git plugin or entered manually. | | `GIT_COMMIT` | The commit SHA. Provided by the Git plugin or replaced with `OX_COMMIT_SHA`. | | `GIT_BRANCH` | The branch name. Provided by the Git plugin or replaced with `OX_SOURCE_BRANCH`. | ### Optional environment variables | Variable | Description | | ---------------------- | ------------------------------------------------------------------------------------ | | `OX_TARGET_BRANCH` | The target branch name. Recommended when running scans before merging pull requests. | | `OX_OVERRIDE_BLOCKING` | Set to `true` to override stage failure caused by blocking issues. | | `OX_TIMEOUT` | Maximum duration of the scan, in minutes. | | `OX_FAIL_ON_TIMEOUT` | Set to `true` to fail the stage if a scan times out. | | `OX_FAIL_ON_ERROR` | Set to `true` to fail the stage if a system or network error occurs. | ### Advanced environment variables | Variable | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------ | | `OX_DISABLE_SSL_VALIDATION` | Set to `true` to disable SSL certificate validation for self-signed certificates in on-premise environments. | ### Integration example (`Jenkinsfile`) ```groovy pipeline { agent any stages { stage('OX Security Scan') { agent { docker { alwaysPull true image 'oxsecurity/ox-block-mode:latest' } } environment { OX_API_KEY = credentials('ox-api-key') // OX_COMMIT_SHA = 6f3f6a038baa67b40f12d0692e75c40ad49a986e // OX_SOURCE_BRANCH = development // OX_TARGET_BRANCH = main // OX_OVERRIDE_BLOCKING = false // OX_TIMEOUT = 20 // OX_FAIL_ON_TIMEOUT = false // OX_FAIL_ON_ERROR = false } steps { script { sh 'ox-block-mode' } } } } } ``` # Azure Pipelines and Azure DevOps Azure Pipelines and Azure DevOps serve as essential tools for enhancing your CI/CD workflows. Azure Pipelines is a cloud-based service that facilitates build and release automation, enabling continuous integration and continuous delivery for applications. Azure DevOps integrates with OX Security Scan Extension, providing additional capabilities to Azure DevOps, and extending its functionality by integrating third-party tools and services. Integrating with OX Security can be achieved through Azure Pipelines for direct CI/CD security measures or using Azure DevOps Extensions for wider functional enhancements, as follows: * [**Azure Pipelines Integration**](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/azure-pipelines-and-azure-devops/azure-pipelines)**:** Embeds security into the CI/CD pipeline, enabling automatic vulnerability scanning during builds. This direct integration focuses on improving security within the CI/CD workflow and requires Docker support for executing security checks. * [**Azure DevOps Integration:**](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/azure-pipelines-and-azure-devops/ox-scan-extension-for-azure-devops) Offers broader customization, allowing the incorporation of third-party tools and services, including security measures. While this provides additional capabilities across Azure DevOps, it's less specialized for CI/CD-specific security than a dedicated Azure Pipelines integration. Choosing between these integrations depends on your specific needs: if you require streamlined security embedded directly into the CI/CD process, Azure Pipelines is ideal. For broader DevOps enhancements, including security across various areas, Azure DevOps Extensions are more suitable. > **Note:** OX Security supports only Git-based repositories in Azure Pipelines / Azure DevOps. Team Foundation Version Control (TFVC) is not supported. If your project uses TFVC, you need to migrate to a Git repository before integrating with OX. # Azure Pipelines OX Security integrates with Azure Pipelines to scan builds for vulnerabilities during the CI/CD process. Azure Pipelines integration is ideal for streamlined security embedded directly into the CI/CD process. ## Prerequisites * **Docker support:** Ensure your Azure agents can run Docker containers and execute `docker run`. ## Required environment variables | Variable | Description | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OX_API_KEY` | [The OX Security integration key.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/creating-ci-cd-integration-key) | ## Optional environment variables | Variable | Description | | ---------------------- | ------------------------------------------------------------------ | | `OX_OVERRIDE_BLOCKING` | Set to `true` to override job failure caused by blocking issues. | | `OX_TIMEOUT` | Maximum duration of the scan, in minutes. | | `OX_FAIL_ON_TIMEOUT` | Set to `true` to fail the job if a scan times out. | | `OX_FAIL_ON_ERROR` | Set to `true` to fail the job if a system or network error occurs. | ## Advanced environment variables | Variable | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------ | | `OX_DISABLE_SSL_VALIDATION` | Set to `true` to disable SSL certificate validation for self-signed certificates in on-premise environments. | ### Integration example (`azure-pipelines.yml`) ```yaml pool: vmImage: ubuntu-latest variables: - group: "OX" stages: - stage: OX Security Scan jobs: - job: OX displayName: Run OX Security Scan steps: - script: | docker run \ -e OX_API_KEY=$(OX_API_KEY) \ --env-file <(env | grep 'SYSTEM_\|BUILD_') \ oxsecurity/ox-block-mode:latest ``` # OX Scan Extension for Azure DevOps OX Security provides an Azure DevOps extension that directly integrates with your pipeline, allowing security scans to be part of your CI/CD process. This integration method is suitable for broader DevOps enhancements, including security across various areas. The overall process involves installing the OX Security Scan Extension from the Azure Marketplace, then authorizing it in your Azure DevOps environment. Following installation, you integrate the extension by creating a service connection with your OX API key, configuring necessary settings, and optionally granting permissions for broader project access. ### Installing OX Security Scan Extension 1. To install the extension from the Azure Marketplace, follow the process [OX Security Scan Extension](https://marketplace.visualstudio.com/items?itemName=oxsecurity.ox-security-scan-task). 2. To authorize the extension: a. Go to **Azure Organization Settings** → **Extensions**. b. Select **OX Security Scan Extension**. c. Ensure there is no **Authorize** button next to the extension name (this confirms authorization is complete). ### Integrating OX Security Scan Extension in your Azure DevOps environment #### Step 1: Creating a service connection 1. Navigate to:\ **Azure Project** → **Project Settings** → **Service connections** → **New service connection**. 2. Search for **OX** and select **OX Security Authentication**. 3. Configure the connection: * Keep the default **Server URL**. * Enter your [**OX API key**](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/creating-ci-cd-integration-key). * Set a **Service connection name**. 4. Optional settings: * Enable **Grant access permission to all pipelines**.\ [Learn more](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/repository-resource?view=azure-devops#add-pipeline-permission-to-a-repository-resource) * Share the service connection across projects:\ [Learn more](https://learn.microsoft.com/en-us/azure/devops/pipelines/policies/permissions?view=azure-devops#set-service-connection-project-permissions)
#### Step 2: (Optional) Adding branch [build validation](https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops\&tabs=browser#build-validation) policies This step allows enforcing scans before merging pull requests. #### Step 3: Adding the OX scan task to your Azure pipeline 1. Edit your [Azure pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/get-started/what-is-azure-pipelines?view=azure-devops). 2. Search for **OX** and [select the **OX Security Scan** task](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/tasks?view=azure-devops\&tabs=yaml). 3. Under **API key**, choose the previously created **Service Connection**. 4. Review and configure other task properties.
| Step Number | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | General Settings | [Make sure the settings are the same as in the General Settings in OX Security.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/pipeline-scan-settings) | | Advanced |
  • Enable debug mode
    Turns on detailed logging to help troubleshoot issues during pipeline scan execution. Use this option only for debugging, as it may generate verbose internal logs.
  • Disable SSL validation
    Skips SSL certificate validation when connecting to external services. Recommended only for testing or non-production environments where SSL certificates may not be trusted.
  • Override blocking issues
    Allows the pipeline to continue even if blocking security issues are detected. Useful in development or staging environments where you want to test despite unresolved issues.
| 5. Each field includes a short description accessible using the ⓘ icon. 6. Add the task as a pipeline step.
* After adding the scan task, you see the **OXSecurityScan** step in your pipeline run.
* When the scan completes, a new **OX Security Scan** tab appears in the Azure DevOps pipeline interface, showing scan results.
# Generic CI You can integrate OX with any CI/CD system that supports running Docker images, even if it’s not listed among the officially supported integrations. This method, called Generic CI Integration, lets you trigger pipeline scans by running the OX Docker image and providing the required environment variables manually. Use this method for CI/CD systems such as Bamboo, TeamCity, or any other platform that can execute Docker containers. Use this integration when: * Your CI/CD system isn’t one of the officially supported platforms. * You need a temporary solution before a native integration is developed. * You’re running OX scans locally or in custom build environments. ### How It Works The Generic CI method runs the same Docker image used for standard pipeline integrations (`oxsecurity/ox-block-mode`), but does not rely on any built-in detection logic for a specific CI system.\ Instead, you provide a small set of environment variables that describe the repository, branch, and commit being scanned. When the scan runs, OX treats it exactly like any other pipeline scan. The results appear in the platform under CI/CD Type: Generic, with the same blocking behavior, vulnerability display, and scan details as native integrations. ### Prerequisites Before you begin: 1. Ensure your CI/CD system can run Docker images. 2. [Obtain an OX API key from your organization’s settings.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/creating-ci-cd-integration-key) 3. Make sure the repository you want to scan is already connected to OX. ### Required Environment Variables | Variable | Description | | ------------------ | -------------------------------------------------------------------------------- | | `OX_GENERIC_CI` | Must be set to `true` to indicate a generic CI execution. | | `OX_API_KEY` | Your OX API key for authentication. | | `OX_GIT_URL` | The repository URL. Provided by the Git plugin or entered manually. | | `OX_SOURCE_BRANCH` |

The name of the branch being scanned, for example:
master

| | `OX_COMMIT_SHA` | The commit SHA, for example: `842cb296ed26a6fd2c59ebdf129d265649877448` | ### Optional Environment Variables | Variable | Description | | ------------------- | --------------------------------------------------------------------- | | `OX_TARGET_BRANCH` | The target branch in case of a pull request, for example: `feature-a` | | `OX_JOB_ID` | The identifier of the CI job. Displayed in OX under the scan details. | | `OX_JOB_URL` | A link to the job run in your CI system. Appears in the OX UI. | | `OX_JOB_USER` | The user or system that triggered the scan. | | `OX_JOB_USER_EMAIL` | The email of the user that triggered the scan. | ### Example The following example shows how to execute a Generic CI scan from any CI/CD system or even locally: ```bash docker run --rm \ -e OX_GENERIC_CI=true \ -e OX_API_KEY= \ -e OX_GIT_URL=https://github.com/example/repo.git \ -e OX_SOURCE_BRANCH=main \ -e OX_COMMIT_SHA=abc123def \ oxsecurity/ox-pipeline-scan:latest ``` You can add optional parameters to include job metadata: ```bash -e OX_JOB_ID=123 \ -e OX_JOB_URL=https://ci.example.com/job/123 \ -e OX_JOB_USER_EMAIL=developer@example.com ``` # Understanding Pipeline Scan Results The scan results appear in the OX platform as follows: * [**Pipeline Summary**:](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/understanding-pipeline-scan-results/pipeline-summary) Includes links to the CI job, affected repository, and number of issues. * [**Pipeline Issues**:](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/understanding-pipeline-scan-results/pipeline-issues) Includes details about each issue, similar to the Active Issues page. # Pipeline Summary The Pipeline Summary page provides a high-level view of all pipeline scans across your organization and lets you drill into specific jobs.
### KPI Cards & Trend Charts | Widget | Description | How to read it | | --------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Pipeline Protected Repos** (donut) | Distribution of repositories protected by pipeline workflows. | Segments show the count per state (for example, **Passed**, **Monitor**, **Blocked**) with a total in the header. | | **Pipeline Scan Status Trend** (line) | Trend of pipeline scan outcomes over time. | Lines track counts per status (Passed/Monitor/Blocked) by date. | | **Pipeline Scan Trends (Grouped by Issue Severity)** (area/bar) | New issues found in pipeline scans, grouped by severity. | Use it to spot spikes in **Critical**/**High** findings after recent changes. | | **Pipeline Duration Trend** (line) | Average or median runtime of pipeline scans over time. | Use to monitor performance regressions in scan duration. | ### Filters Panel Use the left panel to narrow results. You can combine multiple filters, save them under My Filters, and clear them at any time. | Filter | What it narrows | Examples / Notes | | -------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Result** | Overall pipeline scan outcome. |

Each pipeline scan is assigned a result based on the outcome of the scan and the workflows that were triggered:

  • Passed: No issues matched a workflow configured with an Alert or Block action. The scan completed successfully without generating monitored or blocked issues.
  • Monitor: The scan found one or more issues that matched a workflow configured with an Alert action. The issues are reported but do not block the pipeline.
  • Blocked: The scan found one or more issues that matched a workflow configured with a Block action. The pipeline is blocked according to the configured workflow.

Each pipeline scan is assigned a result based on the outcome of the scan and the workflows that were triggered.

Issues that remain in the Discovered state on the Pipeline Issues page are not included in the counts displayed for a pipeline.
For more information about the individual issues that contributed to the pipeline result, see Pipeline Issues.

| | **Application** | Specific app/repository. | Filters all widgets and the grid to the selected app(s). | | **Severity** | Findings severity considered in results. | Critical, High, Medium, Low. | | **Event Type** | Source-control event that triggered the scan. | Push, Pull/Merge Request. | | **CI/CD Type** | The CI/CD system used. | GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, Azure Pipelines, etc. | | **Scanned Branch** | Branch name or pattern. | `main`, `release/*`, feature branches. | | **Source Branch** | The branch containing the changes that triggered the pipeline scan. | For example, `main`, `development`, or a feature branch. | | **Target Branch** | The branch into which the source branch changes are intended to be merged. | Available for pull request or merge request scans. For example, `main` or `release`. | | **App Tag** | Application labels/tags. | Use tags for teams, services, or risk groups. | | **Job Triggered By** | Who initiated the job. | Username/service account. | | **Job ID** | Specific pipeline job identifier. | Paste or select a known ID to jump to that job. | | **Scan Completion Status** | Technical execution status. | Completed, Timed out, Error. | | **Scan Type** | What was scanned. | Code, Container image, etc. | | **Artifact** | Artifact identifier/name (if applicable). | Image digest/name, package, etc. | | **Artifact Tag** | Artifact tag or label. | For example, `v1.2.3`, `latest`. | ### Results Grid The table lists each pipeline scan. Most cells link to details. | Column | What it shows | Interactions / Notes | | ------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Job ID** | Unique identifier for the pipeline scan job. | Click to open the job’s details page (summary, issues, logs). | | **Scanned Branch** | Branch that triggered the scan. | Helps correlate findings to code paths/releases. | | **App Name** | The application (repository) scanned. | Click to open the app overview (depending on permissions). | | **Scan Type** | The kind of scan that ran. | Indicates whether the scan was for Source Code or a Docker Image. | | **Triggered By** | User or system that started the scan. | Shows avatar/name when available. | | **Issues** | Whether issues were detected. | A check (✓) means no issues of interest. A number indicates count of issues that met your workflow conditions. | | **Blocking** | Whether the workflow triggered a **block** action. | ✓ means not blocked. You may also see a ratio such as **0 out of 1** (blocked rules matched / total blocking rules). | | **Date** | When the scan completed. | Uses your selected time range. | ### Common Tasks * **Check organization health:** Use the Pipeline Protected Repos donut and Status Trend chart to see protection coverage and outcome trends. * **Investigate recent spikes:** Look at Pipeline Scan Trends (Grouped by Issue Severity) to spot increases in Critical/High findings; filter by Application or Scanned Branch to localize. * **Review slow scans:** Use Pipeline Duration Trend and filter by CI/CD Type or Application to find regressions and tune performance. * **Drill into a specific job:** Find the row by Job ID or apply filters, then click Job ID to open details, such as issues, policy matches, and actions taken. # Pipeline Issues The Pipeline Issues page presents all the issues found during pipeline scans. You can configure [pipeline workflows](/automate-with-ox-workflows/pipeline-workflows) to react differently to new vs. old issues.
Pipeline issues include an additional status field that does not exist in the Active Issues page: * **New**: Issue did not appear in previous scans. * **Old**: Issue already exists in the Active Issues page. ### Understanding Pipeline Issue Results Pipeline issues can have one of the following results:
ResultDescription
DiscoveredThe issue was detected during the pipeline scan. All newly detected pipeline issues start in this state.
MonitoredThe issue matched a workflow that contains an Alert action. The issue is reported and tracked but does not block the pipeline.
BlockedThe issue matched a workflow that contains a Block action. The issue contributes to blocking the pipeline according to the configured workflow.
The results shown on this page contribute to the overall pipeline scan result displayed on the [Pipeline Summary](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/understanding-pipeline-scan-results/pipeline-summary) page. * If one or more issues are Blocked, the pipeline result is Blocked. * If no issues are blocked but one or more issues are Monitored, the pipeline result is Monitor. * If no issues are monitored or blocked, the pipeline result is Passed. # Docker Image Scanning in CI/CD Pipelines OX Security supports scanning container images immediately after they are built in your CI/CD pipeline. This allows you to detect vulnerabilities at the earliest possible stage, before the image is pushed to a registry or used in any runtime environment. The scan is performed as a dedicated pipeline step, using an OX-provided scanner image and configuration. The integration runs within CI/CD pipelines for repositories that are monitored in OX. First, you need to configure the container scanning, and then you can view the results, as follows: 1. [Pipeline Configuration (Outside OX)](#pipeline-configuration) 2. [Workflow Configuration (Inside OX)](#pipeline-workflow-configuration) 3. [Viewing Scan Results](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/understanding-pipeline-scan-results) ### Pipeline Configuration To scan Docker images during pipeline execution, you must add a new step to your CI/CD configuration. OX provides a Docker image published on Docker Hub that runs the scanner: . #### Prerequisites * OX CI/CD Integration key * Docker image name and tag to be scanned * CI/CD environment that supports injecting environment variables * CI/CD environment that supports mounting the host's Docker socket into the container, OR providing remote access to the Docker daemon using TCP ### Environment Variables The scanner is configured entirely through environment variables. > On GitHub Actions, every variable below can also be supplied with an `INPUT_` prefix (for example, `INPUT_OX_API_KEY`). #### Core configuration | Variable | Required | Default | Description | | ------------- | -------- | ------- | -------------------------------------------------------- | | `OX_API_KEY` | Yes | — | Authentication credentials for the OX platform. | | `OX_HOST_URL` | Yes | — | URL of the OX platform. | | `OX_MODE` | Yes | `scan` | Set to `docker_scan` to run the container image scanner. | #### Selecting the image to scan Provide the image by name plus a tag or digest, or point directly at a pre-saved image tarball. | Variable | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OX_ARTIFACT_NAME` | Name of the Docker image to scan (for example, `myregistry.com/myapp`). | | `OX_ARTIFACT_TAG` | Tag of the image to scan (for example, `v1.0.0` or `latest`). Provide either a tag or a digest. | | `OX_ARTIFACT_DIGEST` | Pin the image by digest instead of a tag. Provide either a tag or a digest. | | `OX_ARTIFACT_TYPE` | Type of artifact being scanned. Accepts `dockerimage`. | | `OX_REGISTRY_TYPE` | Registry type for the image. Accepts `awsecr` for Amazon Elastic Container Registry. | | `OX_ARTIFACT_PATH` | Path to a pre-saved image tarball. When set, the image is scanned directly from the file instead of being pulled from the Docker daemon — skipping the image export step. When provided, `OX_ARTIFACT_NAME` and the tag/digest become optional. | | `OX_DOCKER_TARGET_PLATFORM` | Target platform for multi-architecture images (for example, `linux/amd64` or `linux/arm64`). | #### Reliability and performance | Variable | Default | Description | | ------------------------------- | ------- | ------------------------------------------------------------------------- | | `OX_TIMEOUT` | `20` | Overall scan timeout, in minutes. | | `OX_CVE_ONLY` | `false` | When `true`, skips secret scanning and scans for CVEs only. | | `OX_DOCKER_SAVE_MAX_RETRIES` | `3` | Number of retry attempts when exporting the image from the Docker daemon. | | `OX_DOCKER_SAVE_RETRY_DELAY_MS` | `3000` | Delay between export retry attempts, in milliseconds. | #### Build behavior and failure handling | Variable | Default | Description | | ---------------------- | ------- | -------------------------------------------------------------------- | | `OX_FAIL_ON_TIMEOUT` | `false` | When `true`, fails the pipeline job if the scan times out. | | `OX_FAIL_ON_ERROR` | `false` | When `true`, fails the pipeline job if the scan encounters an error. | | `OX_OVERRIDE_BLOCKING` | `false` | When `true`, prevents blocking issues from failing the build. | | `OX_EXIT_CODE_SUCCESS` | `0` | Exit code returned on a successful scan. | | `OX_EXIT_CODE_WARNING` | `0` | Exit code returned when the scan completes with warnings. | | `OX_EXIT_CODE_ERROR` | `1` | Exit code returned when the scan fails with an error. | #### Output | Variable | Description | | ----------- | --------------------------------------- | | `OX_OUTPUT` | File path to write the scan results to. | #### Debugging and security | Variable | Default | Description | | --------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OX_DISABLE_SSL_VALIDATION` | `false` | When `true`, disables TLS certificate validation. Use only in trusted environments — disabling certificate validation exposes connections to interception. | ## Scanning Methods The OX container scanner supports two ways to access the image, as follows: * Connecting to a running Docker daemon and identifying the image by name and tag * Skipping the daemon entirely and pointing the scanner at a pre-saved image tarball. Both methods produce the same scan results; the choice depends on what your CI/CD environment supports and how your pipeline is structured. #### Scanning with Docker daemon The scanner connects to a running Docker daemon, which exports the image by name and tag for scanning. This is the default method. | Variable | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `DOCKER_HOST` | Address of the Docker daemon. Use a mounted socket such as `unix:///var/run/docker.sock` (local default), or a remote endpoint such as `tcp://192.168.1.100:2375`. | When the image is not already present locally and must be pulled from a registry, the pull uses the credentials configured on the Docker daemon. Set `OX_ARTIFACT_NAME` and `OX_ARTIFACT_TAG` (or `OX_ARTIFACT_DIGEST`) to identify the image to scan. #### Scanning with the Tarball file Instead of connecting to a Docker daemon, you can save the image to a tarball file and point the scanner directly at it. The scanner reads the image from the file, bypassing the Docker daemon entirely. Set `OX_ARTIFACT_PATH` to the path of the tarball. When this is set, `OX_ARTIFACT_NAME` and the tag/digest become optional, and `DOCKER_HOST` is not required. This is useful when: * Your CI/CD environment does not support Docker socket mounting. * The image has already been built and saved to disk as part of an earlier pipeline step. * You want to avoid an additional image export step. {% hint style="info" %} **Secret scanning size limit:** Files larger than 2 MB are skipped during secret scanning. {% endhint %} ### System Requirements | Requirement Type | CPU | Memory | | ---------------- | --------- | ---------- | | Minimum | 1 core | 512 MB RAM | | Recommended | 1–2 cores | 1 GB RAM | ### CI/CD Platform Examples The scanner automatically detects the CI/CD environment it runs in. Supported platforms include: * [GitHub Actions](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/github-actions.md) * [GitLab CI/CD](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/gitlab-ci-cd.md) * [Bitbucket Pipelines](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/bitbucket-pipelines.md) * [Jenkins](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/jenkins.md) * [Azure Pipelines and Azure DevOps](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/azure-pipelines-and-azure-devops.md) * BuildPiper * Generic CI (set `OX_GENERIC_CI` when running in an unlisted environment) #### Example: GitLab CI ```yaml image_scan: stage: scan image: oxsecurity/ox-image-scanner:latest variables: OX_API_KEY: OX_ARTIFACT_NAME: OX_ARTIFACT_TAG: DOCKER_HOST: ``` #### Example: Azure Pipelines ```yaml - job: OX displayName: OX Security Image Scan steps: - script: | docker run \ --rm \ -e OX_API_KEY= \ -e OX_ARTIFACT_NAME= \ -e OX_ARTIFACT_TAG= \ -e DOCKER_HOST=unix:///var/run/docker.sock \ --env-file <(env | grep 'SYSTEM_\|BUILD_') \ -v /var/run/docker.sock:/var/run/docker.sock \ oxsecurity/ox-image-scanner:latest ``` ## Pipeline Workflow Configuration After configuring the pipeline, you must define how OX handles the scan results. This is done in the [Pipeline Workflows area of the OX platform.](/automate-with-ox-workflows/pipeline-workflows) **To configure the workflow:** 1. Go to **Pipeline Workflows** in the OX UI. 2. Drag the **Container Security** policy from the left panel into your active workflow. 3. Define actions based on issue severity or type (e.g., alert, block the pipeline).
4. Save the updated workflow. # Securing Docker Images > **Note:** This capability is currently in Early Access (EA) and is not generally available. To request access, please contact OX technical support. You can securely sign your Docker images stored in AWS Elastic Container Registry (ECR) using AWS Signer. This process ensures the integrity and authenticity of Docker images by centralizing signing requests within OX app, providing you clear visibility into the signing activities. By incorporating artifact signing into your CI/CD pipelines, you can streamline operations and enhance software supply chain security. The following guidelines present the necessary steps to configure and execute securing Docker images, including granting OX the required permissions and integrating the signing process into your workflow. ### Granting AWS Signer Permissions You can grant AWS Signer permissions only for a signing profile that you already have in AWS Signer. #### To grant AWS Signer Permissions: 1. Navigate to the **AWS Signer** service in your AWS Management Console. 2. Create a new signing profile that aligns with your specific requirements. For container image signing, we recommend selecting the appropriate platform, such as `Notation-OCI-SHA384-ECDSA`. 3. Save the signing profile name for the granting access process. 4. To grant access to your signing profile, use the AWS Command Line Interface (CLI) and execute the following command: ```bash aws signer add-profile-permission \ --profile-name "" \ --principal "" \ --action signer:SignPayload \ --statement-id "" \ --region ``` | Parameter | Description | | ---------------------- | ----------------------------------------------------------------------------------- | | `` | The name of the signing profile in AWS Signer. | | `` | The AWS Account ID of OX that is granted the permission. | | `signer:SignPayload` | The action to be allowed, which in this case is the ability to sign payloads. | | `` | A unique identifier for the permission statement, e.g., "OxSecurityAccountSigning". | | `` | The AWS region where the signing profile and related resources are located. | 5. Ensure that the JSON policy remains valid after adding this statement. 6. Save the updated repository policy. 7. To verify the AWS Signer permissions, use the following AWS CLI command or review the repository policy directly within the ECR console: ```bash aws signer list-profile-permissions --profile-name "" ``` ### Granting ECR Repository Permissions 1. In the **Amazon ECR** console, select the repository that contains the Docker images you intend to have signed. 2. Navigate to the **Permissions** tab and click **Edit repository policy**. 3. To allow OXSecurity AWS account to push images, add the following policy statement to your existing repository policy: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCrossAccountAccess", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam:::root" }, "Action": [ "ecr:BatchCheckLayerAvailability", "ecr:BatchGetImage", "ecr:CompleteLayerUpload", "ecr:GetDownloadUrlForLayer", "ecr:InitiateLayerUpload", "ecr:PutImage", "ecr:UploadLayerPart" ] } ] } ``` 4. Save the updated repository policy. # Gradle Dependency Resolution in CI/CD Gradle projects require dependency resolution to run in the same environment where the project is built. Because `build.gradle` files can include executable logic, environment-specific paths, and private repositories, dependency analysis must occur inside the CI pipeline to ensure accurate results. To support this, OX Security provides a CI-based dependency resolver that integrates directly into your Gradle build process. Supported CI platforms include GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure DevOps, and Jenkins, with minor configuration differences Gradle - CI\_CD integration. Gradle dependency resolution cannot be reliably inferred through static analysis alone. Running the resolver inside the CI pipeline provides the following benefits: * **Context awareness:** Uses the same credentials, environment variables, and repository access as the build. * **Accurate dependency graphs:** Dependencies are captured directly from Gradle, without guessing or inference. * **Improved SBOM quality:** The resulting SBOM reflects the dependencies actually used at build time. This approach avoids common issues such as missing private dependencies or incorrect version resolution Gradle - CI\_CD integration. ## How the Gradle CI dependency flow works During a typical CI run, Gradle resolves dependencies using credentials, environment variables, and internal repositories that are available only at build time. OX integrates into this flow by running a lightweight binary inside the same pipeline step. This approach allows OX to: * Capture the exact dependency tree resolved by Gradle. * Generate accurate dependency graphs for each `build.gradle` file. * Reuse collected dependency data in future scans. A typical Gradle CI pipeline with OX integration follows these stages: 1. **Checkout source code:** The CI system pulls the repository from the source control platform. 2. **Materialize secrets:** Credentials and environment variables are injected for access to private repositories. 3. **Resolve dependencies and build:** Gradle resolves dependencies and builds the project using the native build context. 4. **Run OX dependency resolver:** The OX CI binary runs inside the pipeline and captures resolved dependency graphs. 5. **Publish artifacts:** Build artifacts are published if all verification steps succeed. This flow ensures dependency resolution happens exactly as Gradle performs it during the build Gradle - CI\_CD integration. ## What happens after the first run After the dependency graphs are successfully collected: * OX stores them securely. * Future scans reuse the stored graphs. * The CI resolver does not need to run again unless dependencies change. This keeps ongoing scans fast and reliable while maintaining accuracy. ## Configure Gradle Dependency Resolution in CI/CD This procedure explains how to enable Gradle dependency resolution using the OX CI SBOM resolver. Before you begin, make sure your Gradle project builds successfully in CI without OX. ### Step 1: Create an OX API key [Create an API key for CI/CD integration](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/creating-ci-cd-integration-key), or reuse an existing key. ### Step 2: Store the API key as a repository secret Define the following repository secret in your CI system: * `OX_API_KEY=` The secret must be available to the pipeline stage that runs the OX CI resolver Gradle - CI\_CD integration. ### Step 3: Ensure Git metadata is available OX requires Git metadata to associate dependency data with the correct repository and commit. **Supported platforms** The following CI platforms are supported natively and require no additional configuration: * GitHub * GitLab * Bitbucket * Azure DevOps Git metadata is collected automatically. **Jenkins pipelines** For Jenkins, you must explicitly set the following environment variables: * `GIT_URL` * `GIT_BRANCH` * `GIT_COMMIT` Use the Jenkins Git plugin to populate these values. An example is provided in the appendix Gradle - CI\_CD integration. ### Step 4: Add a pipeline stage for the OX resolver Add a new pipeline stage with the following placement rules: * Run the stage **after** the Gradle build step * Run the stage **before** any OX blocking or enforcement stages, if used This ensures Gradle has fully resolved dependencies before OX collects them Gradle - CI\_CD integration. ### Step 5: Download and run the OX CI SBOM resolver In the new pipeline stage: 1. Download the `ox-ci-sbom` binary for your runner architecture: AMD64: \ ARM64: 2. Grant execute permissions. 3. Run the binary. The resolver automatically detects all `build.gradle` files and captures the resolved dependency graph Gradle - CI\_CD integration. ### Step 6: Verify successful execution After the pipeline runs: * Confirm the `ox-ci-sbom` client completes successfully. * Verify that a success message appears in the pipeline logs. If the resolver fails, dependency data is not sent to OX Gradle - CI\_CD integration. ### Step 7: Enable the capability for your organization After the first successful run, contact OX Support and request enablement of the Gradle CI SBOM resolver for your organization. This step is required for results to appear in OX. ### \[Optional] Improve performance using parallel execution The OX CI SBOM resolver can process Gradle dependency data in parallel to reduce execution time. By default, the resolver runs with a conservative level of parallelism. You can explicitly allow it to use multiple CPU cores available on the CI runner. This is useful for repositories with: * Multiple `build.gradle` files * Large dependency graphs * Long Gradle resolution times **How parallel execution works** When enabled, the resolver runs multiple parsing threads in parallel.\ Each thread processes Gradle dependency data independently. The maximum number of parallel threads is limited by the number of CPU cores available to the machine running the pipeline step, such as a container or pod in your CI environment. **To enable parallel execution, define the following environment variable in your CI pipeline:** ``` OX_USE_CPUS_NUM=N ``` Where `N` is the number of CPU cores the resolver is allowed to use. For example: * `OX_USE_CPUS_NUM=2` limits execution to two cores * `OX_USE_CPUS_NUM=4` allows up to four parallel threads **Recommendations** * Set this value based on the CPU resources allocated to your CI runner. * Avoid setting a value higher than the number of available cores. * Increasing this value improves performance but does not affect scan accuracy or results. This setting is optional and can be adjusted without changing the pipeline structure. # Scanning Selected Repositories Running a full scan triggers a system-wide process that consumes significant resources. During this time, the OX platform is partially unavailable. A selective scan is faster than a full scan. During the scan, you can view and filter applications in the Applications page. Instead of waiting for the next scheduled scan or triggering a full scan across all applications, you can run a selective scan when you need to scan a specific application urgently. For example, if you make changes to a repository during the day and want to scan it immediately, you can run a selective scan instead of scanning the entire organization. > **Note:** You can use this option to scan only repositories that have already been scanned at least once. When using selective scan, you can: * Select up to five repositories. * Include only code repository applications. Repository applications are those connected to source control systems such as GitHub, GitLab, Bitbucket, and so on. * Review audit logs that record this scan activity for traceability. **To scan selected repositories:** 1. In the **OX Security** platform, go to **Applications**. 2. Select up to 5 code repo applications and click the select repo scan button on the top bar.
# Scanning Multiple Branches You can streamline your security management across multiple branches while maintaining comprehensive visibility into potential vulnerabilities. Multi-Branch Scanning allows OX to scan multiple branches within a repository, extending your security coverage beyond the default branch. This capability enables you to scan branches that represent: * Various versions of your software * Various stages of development, such as development, staging, and production ### How Multi-Branch Scanning Works When you enable Multi-Branch Scanning, you can scan up to five branches in a repository. If the default branch scanning option is enabled, the default branch counts toward this limit. Each scanned branch is treated as a separate application, with its own findings, trends, and scan history. Enabling the capability can change how the system operates, and it may affect existing data or issue handling. You can expect potential delays or changes in the data and issue resolution process, as the scan process becomes more complex. You can define which branches to scan in the following ways: * [for all repos](#securing-branches-in-all-repos) * [for an individual repo](#securing-branches-of-an-individual-repo) The following table summarizes how the branch scanning settings work together. | Multi-Branch Scanning | Scan default branch | Result | | --------------------- | ------------------- | ------------------------------------------------------------------------------ | | Disabled | Enabled | Only the default branch is scanned. | | Enabled | Enabled | OX scans the default branch and up to four additional selected branches. | | Enabled | Disabled | OX scans only the selected non-default branches, up to five branches in total. | ## Enabling the capability and securing branches in all repos Initially, the capability is disabled, and only the branch that is defined as the default is scanned. > **Note:** To enable the Multi-Branch capability, contact OX Security Technical Support at , or contact your regional customer success manager. **To define branches for scanning:** 1. Go to **Settings** > **Applications** and scroll down to the **Branch Scanning** section.
2. Enable **Multi-branch scan**. 3. To set specific branch names for scanning in all repos, add branch name(s) in the **Branches for scanning** box. > **Note:** > > * If you request a branch that does not exist, the system creates an irrelevant application for this branch. For example, you request to scan the branch named `version-1-3-front-end`. OX platform searches all the repos for this branch name and creates irrelevant apps each time it is not found. > * OX Security supports wildcards for branch scanning. You can use this to automatically capture any branch that follows a specific naming convention without having to add them manually. For example, if you type `test`, any branch with this word will be included. 2. Select **UPDATE**. ## Securing branches of an individual repo When Multiple-branch scan is [enabled](#enabling-the-capability-and-securing-branches-in-all-repos), you can specify which branches to scan in each repo. You can scan up to 4 branches in each repo, the default branch and 3 other branches that you select. When multiple branches are selected for scanning from a specific repo, OX designates one branch as the primary application. It’s marked with a unique icon and you can filter the Applications table using the Primary Application tag. The primary application performs several roles, including receiving issues from third-party integrations, artifact scanners, Git posture, and cloud checks and so on.

Primary Application

**To set branches for scanning in a specific repo:** 1. In the **Connectors** page, select the source control system that you use to integrate with the OX platform. 2. In the **Configure \[source control name] Credentials** dialog, select the gear icon next to **DELETE**.
3. In the **Configure your** \[**source control name] Connector** dialog, select the repos that you want to scan.
4. To specify which branches to scan in the selected repo, click the gear icon next to the repo and select up to 4 branches, including the default one, in the **Select Branches to Scan** dialog.
5. Click **SELECT**. The **Select Branches to Scan** dialog closes. > **Note:** Selecting specific branches for scanning overrides the global branch-scanning settings. 6. In the **Configure your** \[**source control name] Connector** dialog, select **SAVE**. Changes take effect after the next scan. # OX IDE Integrations OX provides IDE integrations that enable scanning code locally during development. These integrations allow you to identify security issues before pushing changes to a remote repository. This option is not a replacement for full repository scans, but a complementary tool for early-stage, local validation. The repository you scan must exist in your organization and be known to OX. Currently the following issue categories are supported: Open Source Security, Code Security, SBOM, IaC, Secret/PII. The main goal is to let you scan code locally before pushing changes to a remote repository, as follows: * Detect vulnerabilities and secrets before they are exposed * Prevent pushing insecure code to shared environments * Fix security issues early in the development process ## How it works IDE integrations scan your local code changes and send them to OX for analysis. Scan results are displayed directly in your IDE and include issues linked to the exact line of code, severity, category, and remediation recommendations. ## Available integrations Choose the integration based on your development environment: * [**VS Code and VS Code-based IDEs:**](/scan-and-analyze-with-ox/scanning/ox-ide-integrations/ox-ide-extension) Use the OX IDE extension for Visual Studio Code, Cursor, Windsurf, and VSCodium. * [**JetBrains IDEs:**](/scan-and-analyze-with-ox/scanning/ox-ide-integrations/ox-ide-plugin) Use the OX IDE plugin for IntelliJ IDEA, PyCharm, WebStorm, GoLand, PhpStorm, and other JetBrains IDEs. # OX IDE Extension (VS Code) The OX IDE extension provides scanning of code changes locally within Visual Studio Code (VS Code) and VS Code–based environments. It integrates with the OX Security platform and is intended for developers working in extension-based IDEs. The extension appears in the IDE sidebar, where you can run scans and review issues directly in your workspace. ## How it works After you [install the IDE Extension](/scan-and-analyze-with-ox/scanning/ox-ide-integrations/ox-ide-extension/installing-the-ox-ide-extension), it appears in the side toolbar with the OX icon, and starts monitoring changes to files in your workspace. You can initiate a scan directly from the IDE, which compresses your local changes and sends them to the OX backend for analysis. Scan results, such as vulnerable dependencies and hard-coded secrets are displayed in a dedicated sidebar, with each issue linked to the exact line of code and accompanied by a recommended fix. You can group these findings by severity or category, filtering the view to focus on critical issues or to see all results at once. Throughout the process, the UI keeps you informed of scan status and messages (for example, **Scan is cancelled**). After a scan completes, the IDE extension displays the detected issues in the left sidebar of your development environment. To help you review and prioritize results more efficiently, the extension supports grouping and filtering options. ## Setting API endpoints for OX cloud services By default OX IDE extension operates on the cloud using settings predefined by OX Security. In addition, you can manually switch to the custom API endpoint. **To define API endpoints:** 1. In the top part of the OX IDE extension, click the gear icon next to the scan button and select **Settings**. 2. To work on-prem or other scenarios, clear **Use predefined API endpoints for OX cloud**, and then in the **Custom API Endpoints** text box, type your local deployment URL.
## Sending logs/events to the telemetry service To support compliance and regulatory opt-out requirements, OX IDE extension can send logs/events to the telemetry service. This option is enabled by default, and you can disable it. **To disable sending logs/events to telemetry service:** 1. In the top part of the OX IDE extension, click the gear icon next to the scan button and select **Settings**.
2. Clear the **Enable telemetry for your VS Code extension** checkbox. ## Running a scan and analyzing the results After installing the OX IDE extension and setting it up, you can start running security scans. When viewing scan results, you can select an issue to navigate directly to the relevant line in the code. This allows you to understand and resolve issues without leaving the OX IDE extension. **To run a scan:** * Click the triangle button on the top. The scan runs and then the results appear with the direct link to the specific location in the code that contains a security risk and remediation recommendations.
Each issue in the list includes the following: * Severity label * Short description * Category * Status * Reference to the affected code line * Suggested fix ### Grouping issues You can organize issues into logical sets for better navigation, as follows: * **By severity:** Displays issues in the following order: Critical, High, Medium, and Low. Use this option to focus on the most urgent issues first.\ OR, * **By category:** Displays issues based on their type: Open Source Security, Code Security, SBOM, IaC, Secret/PII. Use this option to address similar types of issues across your codebase. Each group is collapsible and expandable. **To group security issues:** * In the top part of the OX IDE extension, click the gear icon next to the scan button and select **Settings**.
### Filtering issues You can use filtering to reduce visual noise and concentrate on the issues that matter most. You can filter which issues to display, based on the severity levels. The Appoxalypse severity level issues are always presented by default and you cannot set the extension not to display them. **To filter security issues:** * In the top part of the OX IDE extension, click the gear icon next to the scan button and select **Settings**.
You’re now ready to start using the OX IDE VS Code extension. # Installing the OX IDE Extension You can install the OX IDE Extension from your IDE marketplace, as follows: * **VS Code Marketplace:** * **Open VSX Marketplace:** > **Note:** If your environment blocks marketplace access, for example, offline or restricted networks, contact OX technical support. ## Requirements * Visual Studio Code ^1.96.0 * Git extension for VS Code * An OX.security account with API access ## Step 1: Start the IDE extension installation 1. In **Marketplace**, search for **OX Security**.
2. Select **Install**. The OX icon appears in the left bar, and a welcome page appears.
3. To login with OAuth, continue to [Login using OAuth](#step-2-login-using-oauth) 4. To login with token, [Generate the IDE/CLI integration key](/scan-and-analyze-with-ox/scanning/ox-ide-integrations/generating-ide-cli-integration-key). ## Step 2: Login using OAuth 1. In the **Welcome to OX Security** page, select **Login via OAuth (OX account required)**.
2. Select **Open**. 3. Log in to OX. > **Note**\ > If your organization requires SSO, sign in using your enterprise email address.
The authorization completion message appears.
The authentication completion message appears.
The message **No issues detected yet** appears on the left and the OX icon appears on the side bar.
The following commands are now available from the side bar: | | | | ----------------------- | ------------------------------------------------------------- | | `Open Settings` | Opens the OX extension settings panel. | | `Report an Issue` | Opens a template to report bugs to the OX GitHub repository. | | `Upload Logs` | Sends logs to telemetry. | | `Focus on Found Issues` | Highlights issues in the sidebar. | | `Sign out` | Sign out of the OX IDE extension and clear the authentication | ## Step 3: Login using token 1. [Generate the IDE/CLI integration key](/scan-and-analyze-with-ox/scanning/ox-ide-integrations/generating-ide-cli-integration-key). 2. In the **Welcome to OX Security** page, select **Configure API Key**. The **Settings** tab opens on the right.
3. Add the API key that you generated in the OX Security platform. The message **No issues detected yet** appears on the left and the OX icon appears on the side bar.
The following commands are now available from the side bar: | | | | ----------------------- | ------------------------------------------------------------ | | `Open Settings` | Opens the OX extension settings panel. | | `Report an Issue` | Opens a template to report bugs to the OX GitHub repository. | | `Upload Logs` | Sends logs to telemetry. | | `Focus on Found Issues` | Highlights issues in the sidebar. | # Deploying the OX IDE Extension with MDM Organizations that centrally manage developer workstations can deploy the OX IDE extension across all managed devices using a Mobile Device Management (MDM) solution instead of requiring each developer to install and configure the extension individually. This deployment method is intended for IT administrators and security teams that want to standardize IDE security across the organization, reduce manual setup, and simplify onboarding. In addition to installing the extension, the deployment can automatically configure the OX API key so developers can start using the extension immediately without performing additional configuration. The installer supports unattended deployment through MDM platforms such as Jamf, Microsoft Intune, Kandji, and other MDM solutions capable of distributing files and running scripts. ## Supported IDEs The deployment process supports the following VS Code-based IDEs: | IDE | Supported | | ------------------ | --------- | | Visual Studio Code | Yes | | Cursor | Yes | | Windsurf | Yes | | VSCodium | Yes | ## Supported operating systems | Operating system | Installer | | ---------------- | -------------------------- | | macOS | `install-ox-extension.sh` | | Linux | `install-ox-extension.sh` | | Windows | `install-ox-extension.ps1` | ## How the installer works For each supported IDE detected on a device, the installer: * Installs the OX IDE extension. * Configures the OX API key, if provided. * Preserves the user's existing IDE settings. * Skips IDEs that are not installed. * Can safely be run multiple times without affecting existing installations. If a local VSIX package is provided, the installer uses it. Otherwise, it attempts to install the extension from the appropriate marketplace. ### Recommended deployment method OX recommends deploying the extension together with the VSIX installation package. Using a VSIX package provides a consistent installation experience across all supported IDEs and does not depend on marketplace availability or internet connectivity. This approach is the most reliable option for organizations that use multiple VS Code-based IDEs or operate in restricted environments. Installing the extension directly from the marketplace is supported for Visual Studio Code but may not be available for other supported IDEs. ## Before you begin Before the deployment process, make sure you have the following files: | File | Purpose | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `install-ox-extension.sh` | Installer script for macOS and Linux, see [Deployment scripts](#deployment-scripts). | | `install-ox-extension.ps1` | Installer script for Windows, see [Deployment scripts](#deployment-scripts). | | OX IDE Extension `.vsix` package *(recommended)* | Installs the OX IDE extension locally without relying on marketplace availability. Recommended for consistent deployment across all supported IDEs. | ## Download a VSIX package If the target machine does not have Internet access or cannot reach the Visual Studio Code Marketplace, download the extension as a VSIX package on another machine and transfer it to the target machine. **To download the VSIX package:** 1. Open **Visual Studio Code** on a machine that has access to the Visual Studio Code Marketplace. 2. Select OX Security extension from the activity bar or by pressing: * **Ctrl+Shift+X** on Windows and Linux. * **Cmd+Shift+X** on macOS. 3. Search for the extension that you want to download.
4. In the search results, right-click the extension and select **Download VSIX**. 5. Choose a destination folder and save the `.vsix` file. 6. Transfer the `.vsix` file to the target machine. ## Deploy on macOS or Linux 1. Distribute the installer script and, optionally, the VSIX package to the target devices using your MDM solution. 2. Make the installer executable: ```bash chmod +x install-ox-extension.sh ``` 3. Run the installer: ```bash ./install-ox-extension.sh --api-key --vsix ./extension.vsix ``` #### Installer options | Option | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--api-key ` | Configures the OX API key for the extension. If omitted, the extension is installed without configuring authentication. | | `--vsix ` | Installs the extension from the specified VSIX package. If omitted or unavailable, the installer attempts to install the extension from the marketplace. | | `--ext-id ` | Overrides the default extension identifier (`oxsecurity.ox-ide`). | ## Deploy on Windows 1. Distribute the installer script and, optionally, the VSIX package to the target devices using your MDM solution. 2. Run the installer: ```powershell powershell -ExecutionPolicy Bypass -File install-ox-extension.ps1 -ApiKey -Vsix .\extension.vsix ``` #### Installer options | Option | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-ApiKey ` | Configures the OX API key for the extension. If omitted, the extension is installed without configuring authentication. | | `-Vsix ` | Installs the extension from the specified VSIX package. If omitted or unavailable, the installer attempts to install the extension from the marketplace. | | `-ExtId ` | Overrides the default extension identifier (`oxsecurity.ox-ide`). | ### Exit codes The installer returns one of the following exit codes, which can be used by your MDM solution to verify deployment status. | Exit code | Description | | --------- | ----------------------------------------------------------------------------------------------------- | | `0` | At least one supported IDE was successfully provisioned, or no supported IDE was found on the device. | | `1` | Invalid arguments were supplied or the operating system is not supported. | | `2` | One or more supported IDEs were found, but none could be successfully provisioned. | ## After deployment Restart the IDE, or reload the IDE window, before the newly installed extension and any configured API key become available. ## Deployment Scripts {% tabs %} {% tab title="Installer script for macOS and Linux" %} ``` #!/usr/bin/env bash # # install-ox-extension.sh # # Universal installer for the OX Security extension on macOS and Linux. # Intended to be run unattended as part of an MDM (Jamf, Intune, Kandji, ...) # or any analogous fleet-distribution mechanism. # # For every supported VS Code-like editor found on the machine it will: # 1. Install the extension - from a local .vsix if one is reachable, # otherwise by extension id from the editor's marketplace. # 2. Write the API key into the editor's user settings.json. # # Supported editors: VS Code, VSCodium, Cursor, Windsurf. # # Usage: # ./install-ox-extension.sh --api-key [--vsix ] [--ext-id ] # ./install-ox-extension.sh # API key as positional arg # # Options: # --api-key API key to write into ox-ide.apiKey (optional; if omitted # the extension is installed but no key is written). # --vsix Path to a local extension.vsix. If reachable it is used # instead of the marketplace. If omitted/unreachable the # script falls back to a marketplace install by id. # --ext-id Marketplace extension id (default: oxsecurity.ox-ide). # -h, --help Show this help. # # Exit codes: 0 = at least one editor handled successfully (or nothing to do), # 1 = bad arguments, 2 = no supported editor handled successfully. set -u EXT_ID="oxsecurity.ox-ide" SETTING_KEY="ox-ide.apiKey" API_KEY="" VSIX_PATH="" # ---------------------------------------------------------------------------- # Argument parsing # ---------------------------------------------------------------------------- print_usage() { sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//' } while [ $# -gt 0 ]; do case "$1" in --api-key) API_KEY="${2:-}"; shift 2 ;; --vsix) VSIX_PATH="${2:-}"; shift 2 ;; --ext-id) EXT_ID="${2:-}"; shift 2 ;; -h|--help) print_usage; exit 0 ;; -*) echo "Error: unknown option '$1'" >&2; exit 1 ;; *) # First bare argument is treated as the API key for convenience. if [ -z "$API_KEY" ]; then API_KEY="$1"; shift else echo "Error: unexpected argument '$1'" >&2; exit 1; fi ;; esac done # ---------------------------------------------------------------------------- # OS detection -> base directory that holds each editor's "/User" dir # ---------------------------------------------------------------------------- SETTINGS_BASE="" if [[ "$OSTYPE" == "darwin"* ]]; then SETTINGS_BASE="$HOME/Library/Application Support" elif [[ "$OSTYPE" == "linux"* ]]; then SETTINGS_BASE="${XDG_CONFIG_HOME:-$HOME/.config}" else echo "Error: unsupported OS '$OSTYPE' (this script is for macOS/Linux)." >&2 echo "Use the PowerShell script for Windows." >&2 exit 1 fi # Resolve the .vsix to an absolute path and verify it is a readable file. VSIX_REACHABLE=false if [ -n "$VSIX_PATH" ]; then if [ -f "$VSIX_PATH" ] && [ -r "$VSIX_PATH" ]; then case "$VSIX_PATH" in /*) : ;; # already absolute *) VSIX_PATH="$PWD/$VSIX_PATH" ;; esac VSIX_REACHABLE=true echo "Using local VSIX: $VSIX_PATH" else echo "Notice: --vsix '$VSIX_PATH' is not reachable; falling back to marketplace." fi fi # ---------------------------------------------------------------------------- # Editor definitions: "Display Name|cli-command| dir name" # The dir name is the folder under SETTINGS_BASE that contains User/settings.json # ---------------------------------------------------------------------------- EDITORS=( "VS Code|code|Code" "VSCodium|codium|VSCodium" "Cursor|cursor|Cursor" "Windsurf|windsurf|Windsurf" ) # Locate an editor CLI. Editors may not be on PATH (common with MDM where the # script runs in a minimal shell), so also probe well-known install locations. resolve_cli() { local cmd="$1" if command -v "$cmd" >/dev/null 2>&1; then command -v "$cmd"; return 0; fi local candidates=() if [[ "$OSTYPE" == "darwin"* ]]; then case "$cmd" in code) candidates+=("/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code") ;; codium) candidates+=("/Applications/VSCodium.app/Contents/Resources/app/bin/codium") ;; cursor) candidates+=("/Applications/Cursor.app/Contents/Resources/app/bin/cursor") ;; windsurf) candidates+=("/Applications/Windsurf.app/Contents/Resources/app/bin/windsurf") ;; esac else candidates+=("/usr/bin/$cmd" "/usr/local/bin/$cmd" "/snap/bin/$cmd" "/var/lib/flatpak/exports/bin/$cmd") fi local c for c in "${candidates[@]}"; do if [ -x "$c" ]; then echo "$c"; return 0; fi done return 1 } # Write SETTING_KEY=API_KEY into a settings.json, creating it if needed. # Prefers jq, then python3, then a sed fallback. update_settings_key() { local settings_file="$1" mkdir -p "$(dirname "$settings_file")" [ -f "$settings_file" ] || echo "{}" > "$settings_file" if command -v jq >/dev/null 2>&1; then local tmp; tmp="$(mktemp)" if jq --arg k "$SETTING_KEY" --arg v "$API_KEY" '.[$k] = $v' "$settings_file" > "$tmp" 2>/dev/null; then mv "$tmp" "$settings_file"; return 0 fi rm -f "$tmp" fi if command -v python3 >/dev/null 2>&1; then SF="$settings_file" SK="$SETTING_KEY" SV="$API_KEY" python3 - <<'PY' && return 0 import json, os path, key, val = os.environ["SF"], os.environ["SK"], os.environ["SV"] try: with open(path) as f: data = json.load(f) or {} if not isinstance(data, dict): data = {} except Exception: data = {} data[key] = val with open(path, "w") as f: json.dump(data, f, indent=2) PY fi # Last-resort sed fallback (best effort; assumes a simple settings.json). if grep -q "\"$SETTING_KEY\"" "$settings_file"; then sed -i.bak -E "s/\"$SETTING_KEY\"[ ]*:[ ]*\"[^\"]*\"/\"$SETTING_KEY\": \"$API_KEY\"/" "$settings_file" else sed -i.bak -E "s/}$/, \"$SETTING_KEY\": \"$API_KEY\"\n}/" "$settings_file" fi rm -f "$settings_file.bak" } # True if EXT_ID is present in the editor's installed-extensions list. # The CLI ids are case-insensitive; compare lowercased. extension_present() { local cli="$1" "$cli" --list-extensions 2>/dev/null \ | tr '[:upper:]' '[:lower:]' \ | grep -qx "$(echo "$EXT_ID" | tr '[:upper:]' '[:lower:]')" } # Install the extension into one editor via its CLI. # A non-zero exit from --install-extension is unreliable across editors (some # exit 0 even when the id is absent from their registry), so success is # confirmed by re-reading --list-extensions afterwards. install_extension() { local cli="$1" name="$2" if [ "$VSIX_REACHABLE" = true ]; then "$cli" --install-extension "$VSIX_PATH" --force >/dev/null 2>&1 if extension_present "$cli"; then echo " ✓ installed from VSIX"; return 0 fi echo " ! VSIX install did not take, trying marketplace ($EXT_ID)" fi "$cli" --install-extension "$EXT_ID" --force >/dev/null 2>&1 if extension_present "$cli"; then echo " ✓ installed from marketplace ($EXT_ID)"; return 0 fi if [ "$VSIX_REACHABLE" = false ]; then echo " ✗ install failed: '$EXT_ID' not found in this editor's registry" >&2 echo " (Cursor/VSCodium/Windsurf use OpenVSX; pass --vsix for a reliable install)" >&2 else echo " ✗ extension install failed for $name" >&2 fi return 1 } # ---------------------------------------------------------------------------- # Main loop # ---------------------------------------------------------------------------- echo "OX Security extension installer (macOS/Linux)" [ -n "$API_KEY" ] && echo "API key: ${API_KEY:0:8}..." || echo "API key: (none provided, key will not be written)" echo ANY_SUCCESS=false ANY_FOUND=false for entry in "${EDITORS[@]}"; do IFS='|' read -r NAME CMD DIRNAME <<< "$entry" SETTINGS_FILE="$SETTINGS_BASE/$DIRNAME/User/settings.json" CLI_PATH="$(resolve_cli "$CMD" || true)" # "Installed" = CLI is present OR the editor's User dir already exists. if [ -z "$CLI_PATH" ] && [ ! -d "$SETTINGS_BASE/$DIRNAME/User" ]; then echo "• $NAME: not found, skipping" continue fi ANY_FOUND=true echo "• $NAME:" ok=true if [ -n "$CLI_PATH" ]; then install_extension "$CLI_PATH" "$NAME" || ok=false else echo " ! CLI not found; cannot install extension (only updating settings)" ok=false fi if [ -n "$API_KEY" ]; then if update_settings_key "$SETTINGS_FILE"; then echo " ✓ API key written to $SETTINGS_FILE" else echo " ✗ failed to write API key for $NAME" >&2; ok=false fi fi [ "$ok" = true ] && ANY_SUCCESS=true done echo if [ "$ANY_FOUND" = false ]; then echo "No supported editors found on this machine. Nothing to do." exit 0 fi if [ "$ANY_SUCCESS" = true ]; then echo "Done." exit 0 fi echo "Completed with errors: no editor was fully provisioned." >&2 exit 2 ``` {% endtab %} {% tab title="Installer script for Windows" %} ``` <# .SYNOPSIS Universal installer for the OX Security extension on Windows. .DESCRIPTION Intended to be run unattended as part of an MDM (Intune, etc.) or any analogous fleet-distribution mechanism. For every supported VS Code-like editor found on the machine it will: 1. Install the extension - from a local .vsix if one is reachable, otherwise by extension id from the editor's marketplace. 2. Write the API key into the editor's user settings.json. Supported editors: VS Code, VSCodium, Cursor, Windsurf. .PARAMETER ApiKey API key to write into ox-ide.apiKey. Optional; if omitted the extension is installed but no key is written. .PARAMETER Vsix Path to a local extension.vsix. If reachable it is used instead of the marketplace. If omitted/unreachable the script falls back to a marketplace install by id. .PARAMETER ExtId Marketplace extension id (default: oxsecurity.ox-ide). .EXAMPLE powershell -ExecutionPolicy Bypass -File install-ox-extension.ps1 -ApiKey 1234567890-NEW-KEY .EXAMPLE powershell -ExecutionPolicy Bypass -File install-ox-extension.ps1 -ApiKey KEY -Vsix .\extension.vsix #> [CmdletBinding()] param( [string]$ApiKey = "", [string]$Vsix = "", [string]$ExtId = "oxsecurity.ox-ide" ) $SettingKey = "ox-ide.apiKey" $ErrorActionPreference = "Continue" # --------------------------------------------------------------------------- # Resolve the .vsix (if any) to an absolute, readable path. # --------------------------------------------------------------------------- $VsixReachable = $false if ($Vsix) { if (Test-Path -LiteralPath $Vsix -PathType Leaf) { $Vsix = (Resolve-Path -LiteralPath $Vsix).Path $VsixReachable = $true Write-Host "Using local VSIX: $Vsix" } else { Write-Host "Notice: -Vsix '$Vsix' is not reachable; falling back to marketplace." } } # --------------------------------------------------------------------------- # Editor definitions. # Name : display name # Cli : CLI executable name (resolved on PATH or well-known locations) # DirName : folder under %APPDATA% holding User\settings.json # --------------------------------------------------------------------------- $Editors = @( @{ Name = "VS Code"; Cli = "code"; DirName = "Code" }, @{ Name = "VSCodium"; Cli = "codium"; DirName = "VSCodium" }, @{ Name = "Cursor"; Cli = "cursor"; DirName = "Cursor" }, @{ Name = "Windsurf"; Cli = "windsurf"; DirName = "Windsurf" } ) # On Windows the editor CLIs are .cmd shims. Probe PATH then common install dirs. function Resolve-Cli([string]$cli) { $cmd = Get-Command "$cli.cmd" -ErrorAction SilentlyContinue if ($cmd) { return $cmd.Source } $cmd = Get-Command $cli -ErrorAction SilentlyContinue if ($cmd) { return $cmd.Source } $candidates = switch ($cli) { "code" { @("$env:LOCALAPPDATA\Programs\Microsoft VS Code\bin\code.cmd", "$env:ProgramFiles\Microsoft VS Code\bin\code.cmd") } "codium" { @("$env:LOCALAPPDATA\Programs\VSCodium\bin\codium.cmd", "$env:ProgramFiles\VSCodium\bin\codium.cmd") } "cursor" { @("$env:LOCALAPPDATA\Programs\cursor\resources\app\bin\cursor.cmd") } "windsurf" { @("$env:LOCALAPPDATA\Programs\Windsurf\bin\windsurf.cmd", "$env:ProgramFiles\Windsurf\bin\windsurf.cmd") } default { @() } } foreach ($c in $candidates) { if (Test-Path -LiteralPath $c) { return $c } } return $null } function Update-SettingsKey([string]$settingsFile) { $dir = Split-Path -Parent $settingsFile if (-not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null } $settings = [ordered]@{} if (Test-Path -LiteralPath $settingsFile) { try { $raw = Get-Content -LiteralPath $settingsFile -Raw if ($raw -and $raw.Trim()) { $parsed = $raw | ConvertFrom-Json foreach ($p in $parsed.PSObject.Properties) { $settings[$p.Name] = $p.Value } } } catch { Write-Host " ! Could not parse existing settings.json; recreating it" $settings = [ordered]@{} } } $settings[$SettingKey] = $ApiKey $json = $settings | ConvertTo-Json -Depth 20 Set-Content -LiteralPath $settingsFile -Value $json -Encoding UTF8 } # True if ExtId is present in the editor's installed-extensions list. function Test-ExtensionPresent([string]$cli) { $installed = & $cli --list-extensions 2>$null if (-not $installed) { return $false } return ($installed | Where-Object { $_.Trim().ToLower() -eq $ExtId.ToLower() }).Count -gt 0 } # Install the extension into one editor via its CLI. # A zero exit code from --install-extension is unreliable across editors (some # exit 0 even when the id is absent from their registry), so success is # confirmed by re-reading --list-extensions afterwards. function Install-Extension([string]$cli, [string]$name) { if ($VsixReachable) { & $cli --install-extension $Vsix --force *> $null if (Test-ExtensionPresent $cli) { Write-Host " + installed from VSIX"; return $true } Write-Host " ! VSIX install did not take, trying marketplace ($ExtId)" } & $cli --install-extension $ExtId --force *> $null if (Test-ExtensionPresent $cli) { Write-Host " + installed from marketplace ($ExtId)"; return $true } if (-not $VsixReachable) { Write-Host " x install failed: '$ExtId' not found in this editor's registry" Write-Host " (Cursor/VSCodium/Windsurf use OpenVSX; pass -Vsix for a reliable install)" } else { Write-Host " x extension install failed for $name" } return $false } # --------------------------------------------------------------------------- # Main loop # --------------------------------------------------------------------------- Write-Host "OX Security extension installer (Windows)" if ($ApiKey) { $preview = if ($ApiKey.Length -ge 8) { $ApiKey.Substring(0,8) } else { $ApiKey } Write-Host "API key: $preview..." } else { Write-Host "API key: (none provided, key will not be written)" } Write-Host "" $anyFound = $false $anySuccess = $false foreach ($ed in $Editors) { $userDir = Join-Path $env:APPDATA (Join-Path $ed.DirName "User") $settingsFile = Join-Path $userDir "settings.json" $cliPath = Resolve-Cli $ed.Cli if (-not $cliPath -and -not (Test-Path -LiteralPath $userDir)) { Write-Host "* $($ed.Name): not found, skipping" continue } $anyFound = $true Write-Host "* $($ed.Name):" $ok = $true if ($cliPath) { if (-not (Install-Extension $cliPath $ed.Name)) { $ok = $false } } else { Write-Host " ! CLI not found; cannot install extension (only updating settings)" $ok = $false } if ($ApiKey) { try { Update-SettingsKey $settingsFile Write-Host " + API key written to $settingsFile" } catch { Write-Host " x failed to write API key for $($ed.Name): $_" $ok = $false } } if ($ok) { $anySuccess = $true } } Write-Host "" if (-not $anyFound) { Write-Host "No supported editors found on this machine. Nothing to do." exit 0 } if ($anySuccess) { Write-Host "Done." exit 0 } Write-Host "Completed with errors: no editor was fully provisioned." exit 2 ``` {% endtab %} {% endtabs %} # OX IDE Plugin (JetBrains) The OX IDE plugin provides scanning of code changes locally within JetBrains IDEs. It integrates with the OX Security platform and is intended for developers working in JetBrains environments such as IntelliJ IDEA, PyCharm, and WebStorm. The plugin is installed through the IDE plugin system and is accessed through the IDE interface, where you can configure settings, run scans, and review issues directly in your code. After a scan completes, the plugin displays the detected issues in the IDE. Each issue is linked to the exact line of code and includes relevant details and remediation recommendations. ### Supported IDEs The plugin supports JetBrains IDEs, including: * IntelliJ IDEA * PyCharm * WebStorm * GoLand * PhpStorm Additional JetBrains IDEs are also supported. ### Requirements * A JetBrains IDE * An OX Security account with API access Before you install the plugin, generate an API key. ## Installing the OX IDE Plugin You can install the OX IDE plugin from your IDE marketplace. **To install the plugin:** 1. [Generate the IDE/CLI integration key.](/scan-and-analyze-with-ox/scanning/ox-ide-integrations/generating-ide-cli-integration-key) 2. In your IDE, go to **Settings**. 3. Select **Plugins**. 4. Open the **Marketplace** tab. 5. Search for **OX Security**.
6. Select **Install**. 7. Click **Apply**, then **OK**. 8. Restart the IDE if prompted. After installation, the plugin appears in the IDE.
### Alternative: Manual installation If the marketplace is not available, install the plugin manually: 1. Go to **Settings**. 2. Select **Plugins**. 3. Click **⚙ > Install Plugin from Disk**. 4. Select the plugin `.zip` file. 5. Click **Apply**, then restart the IDE. ### Configuring the plugin After installation, you can configure the plugin. **To configure the plugin:** 1. Go to **Tools > OX Security**.
2. Enter the API key that you generated. 3. (Optional) Configure additional settings such as endpoint or telemetry. 4. Click **Apply**, then **OK**. ### Running a scan and analyzing the results After installing the plugin and setting it up, you can start running security scans. **To run a scan:** * Click the scan button in the plugin.
The scan runs, and the results appear in the IDE.
Each issue includes: * Severity label * Short description * Category * Reference to the affected code line * Suggested fix
Now you can review issues directly in the code and navigate to the relevant lines. # Generating IDE/CLI Integration key Before you install IDE integrations, you need to generate an API key. > **Note:** A user with Admin and Developer roles can create an API Key for the IDE extension. The API Key will be created according to the user's scope. **To generate an API key:** 1. From the left pane of OX Security platform, select **Settings > API Key Settings**. 2. In the **API Key Settings** window, select **CREATE API KEY**. 3. In the **Create API Key** dialog, set the following:
| | | | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **API Key Name** | Add a meaningful name that is easy to identify. It is good practice to include the key's intended purpose in the name. | | **API Key Type** | Select **IDE/CLI Integration**. | | **Expiration Date** | Until when you can use this key. | 4. Select **CREATE**. The key appears.
5. Copy and save the API Key Secret to be used when connecting to APIs. This is the only time when you can see and copy the key. 6. Select **CLOSE**. The new key appears in the **API Key Settings** page.
# OX CLI The OX CLI lets you run OX security scans directly from the command line. It helps you identify security issues early in the development process by scanning your code before committing changes or as part of your development workflow. With the OX CLI, you can: * Scan code on demand from the command line. * Automatically scan code before committing or pushing changes by using Git hooks. * Focus scans on specific security categories. * Configure the CLI to match your environment and workflow. ### Typical workflow Use the following workflow to get started with the OX CLI: | Step | Description | | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | [**1. Install OX CLI**](/scan-and-analyze-with-ox/scanning/ox-cli-1/installing-ox-cli) | Install the CLI, verify the installation, and keep it up to date. | | [**2. Authenticate OX CLI**](/scan-and-analyze-with-ox/scanning/ox-cli-1/authenticating-ox-cli) | Choose and configure the authentication method that best fits your workflow. | | [**3. Scan code with OX CLI**](/scan-and-analyze-with-ox/scanning/ox-cli-1/scanning-code-with-ox-cli) | Choose between manual scans and Git hook integration based on your development workflow. | | [**4. Configure OX CLI (Optional)**](/scan-and-analyze-with-ox/scanning/ox-cli-1/configuring-ox-cli) | Customize CLI settings, such as the API endpoint, telemetry, and environment variables. | # Installing OX CLI The OX CLI lets you run OX security scans directly from the command line. This page explains how to install and maintain the CLI. After installation, continue to [OX CLI authentication](/scan-and-analyze-with-ox/scanning/ox-cli-1/authenticating-ox-cli). ## Prerequisites Before you begin the installation process, make sure the following tools are installed: * [Node.js](https://nodejs.org/), version 16 and newer * npm * [Git](https://git-scm.com/downloads) ## Installing OX CLI The CLI installation method is for users installing from the public npm registry. **To install OX CLI:** ```bash npm install -g @oxappsec/ox-cli ``` ### Verifying successful installation To verify that the CLI is working, run `ox-cli --version`. The available commands, options, and the current version appear.
### Updating OX CLI **To update OX CLI, update public NPM builds:** * Run: ``` ox-cli update ``` **To verify the update in both distributions:** ```bash ox-cli --version ``` ### Uninstalling OX CLI **To uninstall OX CLI, run:** ```bash npm uninstall -g @oxappsec/ox-cli ``` # Authenticating OX CLI Before you can run scans with the OX CLI, authenticate the CLI using one of the supported authentication methods. Choose the method that matches your workflow. | Authentication method | Use when | What it does | | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | [**OAuth**](/scan-and-analyze-with-ox/scanning/ox-cli-1/authenticating-ox-cli/connect-ox-cli-with-oauth) | You want a modern sign-in flow and don't want to create or manage API keys. | Authenticates the CLI through your OX account and stores authentication tokens for subsequent commands. | | [**VibeSec**](/scan-and-analyze-with-ox/scanning/ox-cli-1/authenticating-ox-cli/connect-ox-cli-with-vibesec) | You already use VibeSec in a supported IDE and want to run a single CLI scan without configuring the CLI separately. | Uses the authentication stored by the IDE for the current scan only. | | [**API key**](/scan-and-analyze-with-ox/scanning/ox-cli-1/authenticating-ox-cli/connect-ox-cli-with-an-api-key) | OAuth authentication isn't available or you prefer to authenticate with a static credential. | Stores an API key in the CLI configuration and uses it for subsequent commands. | # Connect OX CLI with OAuth OAuth provides a streamlined way to authenticate the OX CLI. Instead of creating and configuring an API key, you sign in with your OX account. After you authenticate, the CLI securely stores the authentication tokens and uses them for subsequent commands. ### Before you begin Make sure that: * The OX CLI is installed. * You have access to an OX organization. ### Authenticate with OAuth 1. Configure the OX API endpoint. ```bash ox-cli config set api-host https://api.cloud.ox.security ``` 2. Configure the CLI to use OAuth authentication. ```bash ox-cli config set api-key oauth ``` This configures the CLI to authenticate using OAuth instead of an API key. 3. Start the OAuth sign-in flow. ```bash ox-cli login ``` 4. Complete the authentication process. Your default browser opens automatically. Sign in to your OX account and complete the authentication flow. After authentication completes successfully, the CLI stores the OAuth tokens locally for future use. You don't need to sign in again until the tokens expire or you sign out. ### Sign out **To remove the stored OAuth tokens:** Run: ```bash ox-cli logout ``` # Connect OX CLI with VibeSec When you already have VibeSec in a supported IDE, you can use the IDE's authentication to run an OX CLI scan without configuring the CLI separately. After the scan completes, the CLI continues using its configured authentication method. VibeSec authentication is supported for the following IDE integrations: * Claude Code * Cursor * Visual Studio Code with GitHub Copilot ### Before you begin Make sure that: * The OX CLI is installed. * A supported OX IDE integration is installed and authenticated. * VibeSec is enabled in the IDE. > **Note** > > The OX IDE integration must already be authenticated. If no valid authentication token is available, the scan fails. ### Run a scan with VibeSec authentication Run the following command: ```bash ox-cli scan --use-vibesec-auth ``` The CLI automatically searches for authentication credentials stored by supported IDE integrations in the following order: 1. Claude Code 2. Cursor 3. Visual Studio Code with GitHub Copilot The first valid authentication token and its associated OX API endpoint are used for the current scan. This authentication applies only to the current scan. Your configured CLI authentication method, such as OAuth or an API key, remains unchanged. # Connect OX CLI with an API key Use an API key when OAuth authentication isn't available or when you prefer to authenticate the OX CLI with a static credential. After you configure the API key, the CLI uses it for subsequent commands until you configure a different authentication method. ### Before you begin [Retrieve your IDE/CLI integration key from the OX platform.](/scan-and-analyze-with-ox/scanning/ox-ide-integrations/generating-ide-cli-integration-key) ### Connect the CLI 1. Configure the API key. ```bash ox-cli config set api-key ``` Alternatively, run the following command and press **Enter** to securely enter the API key interactively. ```bash ox-cli config ``` 2. (Optional) Configure the OX API endpoint. Configure a custom API endpoint only if you're connecting to an environment other than the default OX Cloud endpoint. ```bash ox-cli config set api-host https://custom.api.endpoint.com ``` 3. Verify the configuration. To verify the configured API key: ```bash ox-cli config get api-key ``` To verify the configured API endpoint: ```bash ox-cli config get api-host ``` > **Note** > > Running `ox-cli config` without arguments is the recommended way to securely enter your API key because the value isn't displayed in your terminal or stored in your shell history. # Scanning code with OX CLI After installing and authenticating the OX CLI, you can scan your code manually or automate scanning by integrating the CLI with Git hooks. Choose the scanning method that best fits your development workflow. | Scanning method | Use when | What it does | | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | [**Manual scan**](/scan-and-analyze-with-ox/scanning/ox-cli-1/scanning-code-with-ox-cli/scanning-code-manually-with-ox-cli) | You want to run scans on demand from the command line. | Scan modified files, entire repositories, or specific security categories. | | [**Git hook integration**](/scan-and-analyze-with-ox/scanning/ox-cli-1/scanning-code-with-ox-cli/integrate-ox-cli-with-git-hooks) | You want scans to run automatically before committing or pushing changes. | Install Git hooks that invoke the OX CLI before Git operations to help prevent risky code from being committed or pushed. | # Scanning Code Manually with OX CLI Manual scans let you analyze your code on demand from the command line. Use the `scan` command to scan modified files, an entire directory, or selected security categories. By default, the OX CLI scans only modified files in the current directory. | Scan mode | Command | Options | Description | Typical use case | | -------------------------------- | ------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **Modified files** | `ox-cli scan` | None | Scans only modified files in the current directory. This is the default behavior. | Scan the changes you're currently working on. | | **Specific directory** | `ox-cli scan ` | `` | Scans the specified directory. If no directory is specified, the current directory is scanned. | Scan a repository or project located outside the current directory. | | **Full scan** | `ox-cli scan --full-scan` | `--full-scan` | Scans all files in the target directory instead of only modified files. | Validate the entire codebase, such as after cloning a repository or before a release. | | **Scan by category** | `ox-cli scan --category ` | `--category ` | Scans only the specified security categories. Specify multiple categories as a comma-separated list. | Focus on specific security checks. | | **Full scan by category** | `ox-cli scan --full-scan --category ` | `--full-scan--category ` | Scans all files in the target directory for the specified security categories. | Validate one or more security categories across the entire repository. | | **Compare against a Git remote** | `ox-cli scan --git-remote-name ` | `--git-remote-name ` | Uses the specified Git remote when determining which files have changed. | Compare changes against a remote other than the default. | | **Use VibeSec authentication** | `ox-cli scan --use-vibesec-auth` | `--use-vibesec-auth` | Uses the authentication token stored by a supported VibeSec IDE integration for the current scan. | Run a scan using your existing VibeSec authentication. | ### Supported scan categories Use the `--category` option with one or more of the following values: | Category | Value | | -------------------------- | --------- | | Code Security | `code` | | Open Source Security | `oss` | | Secrets and PII | `secrets` | | Infrastructure as Code | `iac` | | Software Bill of Materials | `sbom` | To scan multiple categories, specify a comma-separated list. Example: ```bash ox-cli scan --category code,secrets ``` ### Examples Scan modified files in the current directory: ```bash ox-cli scan ``` Scan a specific directory: ```bash ox-cli scan ./my-project ``` Run a full scan: ```bash ox-cli scan --full-scan ``` Run a full scan for a specific directory: ```bash ox-cli scan ./my-project --full-scan ``` Scan only Secrets and Infrastructure as Code issues: ```bash ox-cli scan --category secrets,iac ``` Run a full scan for Open Source Security issues: ```bash ox-cli scan --full-scan --category oss ``` Scan Code Security and Secrets issues and display only Critical and High severity findings: ```bash ox-cli scan --category code,secrets --severity Critical,High ``` # Integrate OX CLI with Git Hooks You can integrate the OX CLI with Git hooks to automatically scan your code before committing or pushing changes. Unlike manual scans, Git hooks run automatically as part of your Git workflow, helping identify security issues without requiring developers to remember to run scans. OX CLI supports two types of Git hook installations: | Installation type | Use when | Description | | -------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [**Repository Git hooks**](#manage-repository-git-hooks) | You want to enable automatic scanning for a specific repository. | Installs Git hooks only in the selected repository. This option is useful when different repositories require different Git hook configurations. | | [**Global Git hooks**](#global-git-hooks) | You want to enable automatic scanning in all repositories on your machine. | Installs Git hooks once by using Git's global `core.hooksPath` configuration. This option is useful when you want the same scanning behavior across all repositories. | ### Before you begin Make sure that: * The OX CLI is installed. * The CLI is authenticated using one of the supported authentication methods. ### Manage repository Git hooks Repository Git hooks apply only to the current repository. | Task | Command | Description | | ----------------------------- | ------------------------------------------------- | ---------------------------------------------------------------- | | **Install a pre-push hook** | `ox-cli install-git-hook --type pre-push` | Installs the default Git hook that scans before pushing changes. | | **Install a pre-commit hook** | `ox-cli install-git-hook --type pre-commit` | Installs a Git hook that scans before each commit. | | **Uninstall a pre-push hook** | `ox-cli uninstall-git-hook --type pre-push` | Removes the installed pre-push hook. | | **Replace an existing hook** | `ox-cli install-git-hook --type pre-push --force` | Replaces an existing non-OX Git hook. | ### Global Git hooks Global Git hooks apply to all repositories on your machine. #### Global Git hook behavior Global Git hooks differ from repository Git hooks in the following ways: | Behavior | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------- | | Target directory | The CLI ignores any target directory that you specify. | | `--force` | Not supported for global Git hooks. | | Existing hooks | Existing global hooks are preserved. OX installs its hook alongside existing hooks and chains their execution. | #### Manage global Git hooks | Task | Command | Description | | ------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------- | | **Install a global pre-push hook** | `ox-cli install-git-hook --global --type pre-push` | Installs the default global Git hook. | | **Install a global pre-commit hook** | `ox-cli install-git-hook --global --type pre-commit` | Installs a global Git hook that scans before each commit. | | **Uninstall a global pre-push hook** | `ox-cli uninstall-git-hook --global --type pre-push` | Removes the installed global pre-push hook. | ### Limitations Global Git hooks have the following limitations: * Repositories that define their own `core.hooksPath` aren't covered because Git gives precedence to the repository-specific configuration. This is common with **Husky**, **lefthook**, and **pre-commit**. Install a repository Git hook for these repositories instead. * A POSIX shell is required. On Windows, Git must be installed with Git Bash or another compatible shell. * If the global hooks directory already contains an OX backup from a previous installation, uninstall the existing global Git hook before installing a new one. # Configuring OX CLI Configure the OX CLI to match your environment and preferences. Use the CLI configuration commands to view or update settings, configure a custom OX API endpoint, enable or disable telemetry, or use environment variables to override configuration values. ### View the current configuration To display the current value of a configuration parameter, run: ```bash ox-cli config get ``` To list all available configuration parameters, run: ```bash ox-cli config get ``` ### Configure the OX API endpoint By default, the OX CLI connects to the OX Cloud API endpoint. If you're connecting to a different environment, such as a staging or development environment, configure a custom API endpoint: ```bash ox-cli config set api-host https://custom.api.endpoint.com ``` ### Configure telemetry The OX CLI can send anonymous usage data to help improve the product. Enable telemetry: ```bash ox-cli config set telemetry true ``` Disable telemetry: ```bash ox-cli config set telemetry false ``` ### Use environment variables You can configure the OX CLI by using environment variables instead of storing configuration values locally. Environment variables are useful for temporary sessions, scripts, and CI/CD pipelines. The following environment variables are supported: | Environment variable | Description | | -------------------- | -------------------------------- | | `OX_API_KEY` | API key used for authentication. | | `OX_API_HOST` | OX API endpoint. | | `OX_TELEMETRY` | Enables or disables telemetry. | Environment variables override locally stored configuration values for the current session. > **Note** > > Environment variables are intended for temporary or automated environments. For interactive use, configure the CLI using the `ox-cli config` commands. # Monorepo Scanning OX supports monorepo scanning, which is scanning repositories that contain multiple services or applications under a single root directory. In OX, a monorepo can be managed either as a single OX application or divided into multiple OX applications using Monorepos Segmented Scanning. This setting controls how the repository is structured in the platform and how risk, policies, and workflows are applied. It does not affect scan depth or detection accuracy. ## When Monorepos Segmented Scanning Is Enabled When enabled, OX divides a single repository into smaller OX applications based on the file names you define in the connector configuration. Each folder that contains at least one of the specified file names is designated as a separate OX application. OX builds a separate dependency graph per segment, evaluates policies per segment, and calculates risk and prioritization at segment level. Each segment appears as an independent OX application in the platform and can follow its own workflow and ticketing configuration. Findings remain mapped to their exact file paths. The segmentation affects organizational structure and risk calculation, not file-level visibility. **To enable and define segmented scanning:** 1. Go to **Settings > Applications**. 2. Enable **Monorepos Segmented Scanning** (Default: enabled). 3. In the **File List** field, enter one or more file names that define application boundaries. File names are case-insensitive. 4. Click **Update**. After saving the configuration, OX designates any folder that contains at least one of the specified files as a separate OX application during subsequent scans. If you modify the file list and click Update, OX applies the updated segmentation rules to future scans. ## When Monorepos Segmented Scanning Is Disabled When segmented scanning is disabled, OX treats the repository root as a single OX application. All detected manifests are analyzed together under one repository context. A unified dependency graph is built, policies apply at repository scope, and findings are aggregated under one application. Findings are still associated with their specific file paths, and full analysis is preserved. Ownership, prioritization, reporting, and workflows are calculated at repository level rather than per service. # Secret and PII Scanning OX scans your environment for exposed secrets and sensitive information across source code, Git history, containers, runtime assets, and CI/CD systems. Different organizations often require different detection behavior depending on their environment, development practices, and security requirements. For example: * Development teams may intentionally use mock credentials or placeholder values that should not generate findings * Organizations may use proprietary token structures or internal credentials that are not recognized by OX by default * Security teams may want to focus remediation efforts only on active and exploitable credentials OX allows you to adapt secret and PII detection behavior to your organization's needs. Custom detection and exclusion patterns apply across supported OX scanning engines. | Area | Supported detections | | ------------------ | ---------------------------------------------- | | Secrets scan | Secrets and PII in code and Git history | | CI/CD posture | Secrets echoed in workflow logs | | Container security | Secrets and PII in containers | | Cloud context | Secrets and PII in runtime and cloud functions | ## Common security goals | Goal | Recommended capability | | --------------------------------------------------------- | ----------------------------------- | | Ignore development-only credentials or placeholder values | Exclude Secret/PII Patterns | | Reduce repeated false positives | Exclude Secret/PII Patterns | | Detect proprietary API tokens or internal credentials | Custom Secret/PII Pattern Detection | | Detect organization-specific PII formats | Custom Secret/PII Pattern Detection | | Prioritize active credentials over inactive secrets | Secret Validation | > Note: Use exclusions to suppress known false positives. Use custom detection to identify additional secrets or PII that OX does not currently recognize. ## Configuring secret and PII detection 1. Go to **Settings** > **Scan settings** > **Secrets**.
2. Enable the required option. | Option | What it does | | ----------------------------------- | ---------------------------------------------------------------- | | Secret Validation | Checks whether supported detected secrets are active | | Exclude Secret/PII Patterns | Prevents matching patterns from being reported as findings | | Custom Secret/PII Pattern Detection | Allows OX to detect organization-specific secret or PII patterns | 3. Configure the required exclusion or custom detection patterns in the relevant section. Changes are applied automatically after they are updated. # Defining Custom Secret and PII Patterns > **Note:** This capability is currently in Early Access (EA) and is not generally available. To request access, please contact OX technical support. You can define custom patterns to detect proprietary secrets, internal credentials, or organization-specific PII formats that are not recognized by OX by default. After a custom pattern is added, it becomes active in subsequent scans across supported OX scanning engines. 1. Go to **Settings** > **Scan settings** > **Secrets**. 2. Enable **Custom Secret/PII Pattern Detection**.
3. In the **Custom patterns** section, select **Add**.
4. In the **Basics** tab, configure the pattern settings. | Field | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | Secret / PII | Defines whether the pattern detects secrets or PII | | Name | Display name for the custom pattern | | Severity | Severity assigned to matching findings | | Pattern (regex) | Regex expression used for matching, see [Requirements for custom regex patterns](#requirements-for-custom-regex-patterns) | | Notes | Internal notes for the pattern | | Custom Issue Description | Custom description displayed in related findings | 5. Optional: In the **Validation** tab, test the Regex pattern against example values before saving the rule.
| Field | Description | | -------------- | ------------------------------------------------ | | Example Secret | Example value used to validate the Regex pattern | 6. Optional: In the **Advanced** tab, configure additional matching controls.
| Field | Description | | ------------ | -------------------------------------------------------- | | Entropy | Additional validation used to improve detection accuracy | | Secret group | Group identifier used during matching | 7. Select **Add**. The pattern becomes active in subsequent scans after it is saved. ## Requirements for custom regex patterns When you add or edit a custom Secret or PII pattern, OX automatically checks that the regex meets a set of requirements before it can be saved. These requirements help ensure that custom patterns: * Use valid regular expression syntax. * Do not negatively affect scan performance. * Are specific enough to detect meaningful secrets or PII without producing excessive matches. If a regex does not meet one or more of these requirements, OX displays an error message explaining why the pattern was rejected. > **Note** > > The **Validation** tab lets you test a regex against sample values. The requirements described in this section are separate checks that OX performs automatically whenever you add a custom regex. ### Syntax requirements The regex must use valid regular expression syntax. Invalid regex patterns cannot be saved. For example, the following regex is invalid because the character class is not closed: ``` [abc ``` ### Performance requirements The regex must not contain patterns that may cause excessive backtracking, also known as **Regular Expression Denial of Service (ReDoS)**. Unsafe regexes can significantly increase scan time and affect scan performance. Examples of patterns that may be rejected include: ``` (a+)+ ``` ``` (.*)* ``` ``` (\w+)+ ``` ### Specificity requirements The regex must be specific enough to detect meaningful secrets or PII without matching excessive amounts of unrelated content. To measure specificity, OX assigns a score to each regex. A regex must achieve a minimum specificity score of **3** to be accepted. The following regex elements contribute to the specificity score. | Regex element | Contribution | | ------------------------------------------------------- | --------------------------------- | | Literal character (for example `a`, `B`, `-`, `_`) | +1 | | Meta character (`.`, `\d`, `\w`, `\s`) | 0 | | Character class (`[a-z]`, `[\s\S]`)\* | Confirm with your OX version | | Sequence | Sum of all elements | | Alternation (`foo\|bar`) | Lowest scoring branch | | Group (`(...)`) | Same score as its contents | | Quantifier with a required minimum (`+`, `{3}`, `{5,}`) | Minimum occurrences × inner score | | Optional quantifier (`*`, `?`) | 0 | | Anchors and assertions (`^`, `$`, `\b`) | 0 | ### Examples | Regex | Result | Explanation | | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------- | | `morrigan-pk_[A-F0-9]{16}` | Accepted | The literal prefix `morrigan-pk_` makes the pattern highly specific. | | `sync://cred_[a-z0-9]{10}@ox` | Accepted | Contains multiple literal components with a variable section, resulting in a highly specific pattern. | | `AKIA[0-9A-Z]{16}` | Accepted | The literal prefix `AKIA` identifies a specific secret format. | | `\w{24}` | Rejected | Uses only a meta character and does not include any literal characters. | | `.*` | Rejected | Matches arbitrary content and is too broad for secret or PII detection. | | `foo\|.*` | Rejected | One branch is overly broad, so the lowest-scoring branch determines the result. | | `ab` | Rejected | Contains only two literal characters and does not meet the minimum specificity requirement. | ### Common validation errors | Error | Cause | Resolution | | ------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- | | Invalid regex | The regex contains a syntax error. | Correct the regex syntax. | | Regex may be vulnerable to ReDoS | The regex contains an unsafe pattern that may affect scan performance. | Simplify the regex and remove nested quantifiers. | | Use at least three literal characters | The regex is too broad and does not meet the minimum specificity requirement. | Add more literal characters or make the pattern more specific. | ## Limits and permissions | Configuration | Value | | ---------------------------------------- | ----------------------- | | Maximum custom patterns per organization | 20 | | Default state | Disabled | | Required permissions | Admin or Policy Manager | # Custom Code Security Scanning Custom Code Security Scanning allows you to extend OX code security scans with organization-specific SAST rules. OX includes built-in SAST rules maintained by the OX Security research team. If your organization uses proprietary frameworks, internal libraries, or coding standards that require additional security checks, you can define your own OpenGrep-compatible rules. These custom rules run together with the built-in OX SAST rules during code security scans. Custom rules supplement the built-in OX detection logic. They do not replace or modify the default OX rules. * Custom SAST Rules are disabled by default. * You can configure up to 50 custom rules per organization. * OX validates the structure of each rule before saving it. It does not validate whether the rule detects the intended code pattern. Test your rule before using it in production. ### Enable custom code scanning To enable or disable Custom SAST Rules: 1. Go to **Settings** > **Scan Settings**.
2. Under **Code Security**, turn **Custom SAST Rules** on or off. When the capability is disabled, OX ignores all configured custom rules during code security scans. ### Add custom code rules 1. Go to **Settings** > **Scan**. 2. Under **Code Security**, select **Add**.
3. Configure the rule. | Setting | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Rule Type** | Type of custom rule. Currently, only **SAST** is supported. | | **Rule Name** | Internal name used to identify the rule in the **Custom SAST Rules** table. This name is not displayed in findings. | | **Issue Name** | Name displayed for findings generated by the rule. Use a descriptive name that reflects the vulnerability or insecure coding pattern detected, such as **JavaScript Eval Function** or **Unsafe SQL Query**. | | **Severity** | Severity assigned to findings generated by the rule. | | **Issue Description** | Description displayed in the finding details. | | **Issue Recommendation** | Remediation guidance displayed in the finding details. | | **Custom Rule** | OpenGrep-compatible rule that defines the code pattern to detect. Select **Test in OpenGrep Playground** to validate the rule before adding it. | 4. Select **Add**. The rule is added to your organization and is evaluated during subsequent code security scans. #### Example custom rule The following example detects JavaScript code that uses the `eval()` function. ```yaml rules: - id: javascript-eval languages: - javascript severity: WARNING message: message pattern: eval(...) ``` ### View and manage custom rules The **Custom SAST Rules** table displays all configured rules. | Column | Description | | --------------- | ---------------------------------------------------- | | **Type** | Rule type. Currently, only **SAST** is supported. | | **Rule Name** | Internal name of the custom rule. | | **Issue Name** | Name displayed for findings generated by the rule. | | **Severity** | Severity assigned to findings generated by the rule. | | **Description** | Description configured for the finding. | To remove a rule, delete it from the table. Findings generated only by that rule are no longer appear in future scans. ### Review findings Findings generated by custom SAST rules appear together with other code security findings. **To locate these findings:** * Filter by the **SAST** policy, and search for the **Issue Name** that you defined for the rule.
Each finding displays the custom **Issue Name**, **Severity**, **Issue Description**, and **Issue Recommendation** that you configured when creating the rule. # Analyzing Scan Results OX unifies findings from your source control, pipelines, registries, cloud accounts, and external testing tools into a single, consistent view. Each result is normalized, deduplicated, linked to its asset and owner, and refreshed on every scan. Use filters to narrow results by application, severity, status, policy, time window, and ownership. Review root cause, exploitability, affected assets, and remediation steps. Track SLAs and confirm fixes with evidence from subsequent scans. Analysis views in OX: * **Active Issues:** A cross-environment list of findings with full context and guidance. Triage, prioritize, assign, and verify fixes with links to code, builds, and assets. * **Applications:** An application-centric summary of posture. See open work, risk indicators, ownership, and progress for each product or service. * **Matching third-party projects to OX apps:** Map external project identifiers (for example, scanner “projects” or repo paths) to OX applications to consolidate results and ownership. Supports automatic suggestions with manual review and API updates. * **Importing issues from external systems:** Bring findings from other scanners or ticketing systems into OX, preserve key metadata, deduplicate against existing results, and keep status synchronized for reporting and audits. # Applications The Applications page provides an inventory of the applications monitored by OX. It helps you understand which applications are connected to OX, assess their security posture, prioritize remediation efforts, and manage application settings across your organization. Depending on the OX capability, an application can represent: * A source code repository * A repository branch * A cloud account * A container image registry * A DAST target URL
Each application represents a code repository, cloud account, container registry, or another supported asset that OX analyzes. Use this page to: * Review the applications monitored by OX. * Prioritize applications based on business importance. * Filter applications by technology, ownership, scan coverage, and other attributes. * Perform bulk actions on multiple applications. * Perform pipeline integration. * Open an application to review its details and associated issues. To review details of each application, select an application name. The [Application Details](/scan-and-analyze-with-ox/analyzing-scan-results/applications/application-details) page provides detailed information about an application's security posture, issues, scan coverage, connected assets, metadata, and related findings. To perform actions in the Application page, see [Manage Applications](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications). ## Applications table Each row represents an application monitored by OX. | Column | Description | | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | [Business Priority](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications/business-priority) | Business priority assigned to the application. OX uses this value as one of the severity factors when calculating issue severity. | | App Name | Name of the application. Select the application to open its details page. | | OX in Pipeline | Indicates whether the application participates in OX pipeline scanning. | | [Tags](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications/application-tags) | Tags assigned to the application. | | Highest Severity Issues | Number of Critical, High, Medium, and Low issues currently associated with the application. | | PBOM | Visual summary of the application's Product Bill of Materials (PBOM). | | Last Code Change | Indicates when the application's source code was last modified. | ## Filter applications Use the filters to display only applications that match specific criteria. You can combine multiple filters to narrow the results. | Filter | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Application | Display one or more specific applications by name. | | Severity | Find applications that contain issues of a specific severity level, helping you prioritize remediation efforts. | | Category | Display applications by asset type, such as repositories, repository branches, cloud accounts, container registries, or DAST targets. | | App Tag | Find applications with specific user-defined and OX-generated tags. Tags can be used to organize applications and define application scopes. | | Custom Tag | Find applications with specific user-defined tags only. | | Application Source | Display applications based on how they were onboarded to OX, such as source control, cloud, container registry, or DAST. | | CI/CD | Find applications associated with a specific CI/CD platform. | | Orchestrator | Display applications deployed through a specific container orchestration platform, such as Kubernetes. | | Registry | Find applications associated with a specific container image registry. | | Artifact Type | Display applications by the type of artifact that OX analyzes. | | Container as a Service | Find applications deployed to managed container services. | | Cloud Deployment | Display applications running in a specific cloud deployment environment. | | Connection Name | Find applications imported through a specific OX connector. This is useful when managing multiple integrations with the same platform. | | SCA Coverage | Find applications that are or are not covered by Software Composition Analysis (SCA). | | SAST Coverage | Find applications that are or are not covered by Static Application Security Testing (SAST). | | Secret Coverage | Find applications that are or are not scanned for exposed secrets. | | IaC Coverage | Find applications that are or are not scanned for Infrastructure as Code (IaC) security issues. | | Security Tool Source | Display applications with findings imported from a specific third-party security tool. | | OX in Pipeline | Find applications that are included in or excluded from OX pipeline scanning. | | Languages | Display applications that contain code written in specific programming languages. | | Package Manager | Find applications that use a specific package manager, such as npm, Maven, or NuGet. | | App Classification | Display applications assigned to a specific application classification. | | Analyzed Branch | Find applications associated with a specific repository branch. | | Business Priority | Display applications within a specific Business Priority range. | | Code-to-Cloud Exposure | Find applications based on their code-to-cloud exposure status. | | CI/CD Type | Display applications by the type of CI/CD platform used to build and deploy them. | ### Related information * [Application Details](/scan-and-analyze-with-ox/analyzing-scan-results/applications/application-details) * [Managing applications](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications) * [Scopes](/admin-settings/scopes) * [Active Issues](broken://pages/RZBT6y0nd3RaSRNT1C27) # Managing Applications You can use the application action bar to manage multiple applications simultaneously. Depending on the selected applications, you can start scans, configure scan settings, assign owners, manage tags, and update other application settings.
Select one or more applications to display the action bar. The available actions depend on the selected applications. ### Available actions | Action | Description | | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Scan Selected Applications](/scan-and-analyze-with-ox/scanning/scanning-selected-repositories) | Start a scan for up to five selected repository applications. | | [Application Scan Settings](/scan-and-analyze-with-ox/scanning/multi-branch-support) |

Configure the scan settings for the selected repository applications.
Note

The Application Scan Settings action is available only when Multi-Branch Scanning is disabled.

If Multi-Branch Scanning is enabled, configure the branches to scan in the source control connector settings.

| | [Pipeline Settings](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/pipeline-scan-settings) | Open the pipeline settings for the selected applications. For more information, see Pipeline Workflows. | | [Manage Tags](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications/application-tags) | Add, remove, or create tags for the selected applications. | | [Assign Owner](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications/application-owners) | Assign or update application owners for the selected applications. | | [Change Business Priority](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications/business-priority) | Update the Business Priority of the selected applications. | # Business Priority Business Priority represents the business importance of an application. OX uses this value as one of the severity factors when calculating issue severity. Business Priority values range from 1 to 100. | Business Priority | Value | | ----------------- | ------ | | Critical | 90–100 | | High | 60–89 | | Medium | 30–59 | | Low | 1–29 | Business Priority can affect the calculated severity of issues associated with an application. * Critical and High Business Priority do not change issue severity. * Medium Business Priority lowers the severity of an issue by one level, except for Secret issues. * Low Business Priority lowers the severity of an issue by two levels, except for Secret issues. * Severity is never reduced below Low. Most policies include an option to ignore the Business Priority severity factor when calculating issue severity (**Settings > Policies**). For example:
### Change the Business Priority You can update the Business Priority for one or more applications simultaneously. **To change the Business Priority:** 1. Go to **Applications**. 2. Select one or more applications. 3. Select **Change Business Priority**.
4. Enter a value between 1 and 100. 5. Select **Apply**. ### Related information * [Managing applications](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications) * [Applications](/scan-and-analyze-with-ox/analyzing-scan-results/applications) * [Active Issues](/scan-and-analyze-with-ox/analyzing-scan-results/issues) # Irrelevant Applications You can review applications that are excluded from the active application inventory, understand why they were marked as irrelevant, and identify repositories that may need to be restored or cleaned up.
Applications can become irrelevant automatically based on repository status or activity, or they can be marked as irrelevant manually by an administrator. The following reasons can cause an application to become irrelevant automatically: | Reason | Description | | -------------------------------------------------- | ----------------------------------------------------------------- | | No code changes in the last *n* days | The repository has not changed for the configured number of days. | | Archived Repo | The repository is archived in the source control system. | | Repository has been set by client to be irrelevant | An administrator manually marked the application as irrelevant. | | Repository is empty | The repository does not contain source code. | | Branch does not exist | The configured branch no longer exists. | | No Relevant Files | OX did not detect supported files in the repository. | In addition to the automatic app being made irrelevant by OX, the admin can manually mark the app as irrelevant. To manually mark application (s) as irrelevant: * On the **Applications** page, select the applications that you want to mark as irrelevant and select **Make Irrelevant**.
# Application Tags Application tags help you organize and categorize applications across the OX platform. You can use tags to: * Organize related applications. * Simplify filtering throughout the OX platform. * Generate reports for groups of applications. * Define application scopes. * Scope policies, workflows, and other OX capabilities. You can assign existing tags, remove assigned tags, or create new tags. ### Tag types OX supports the following types of application tags:
Tag typeDescription
OX-generated tagsTags that OX automatically assigns based on application metadata, such as the source control provider, cloud provider, programming language, package manager, or other detected attributes. OX-generated tags are read-only.
User-defined tagsCustom tags that you create and manage to organize applications according to your organization's needs. You can use these tags for filtering, reporting, policies, workflows, application scopes, and other OX capabilities.
### Best practices * Use a consistent naming convention for tags across your organization. * Use tags to group related applications, such as [business units](/generate-reports/built-in-reports/executive-reports#creating-business-units), teams, environments, or projects. * Avoid creating multiple tags that represent the same logical group. * Use tags consistently when defining [application scopes](broken://pages/2OEAUmhkBPZnqcSIPLGU). ### Configure application tags You can configure tags for one or more applications simultaneously. **To configure application tags:** 1. Go to **Applications**. 2. Select one or more applications. 3. Select **Manage Tags**.
4. In the **Add or Edit Tags** dialog, do one or more of the following: * Select one or more existing tags. * Clear assigned tags to remove them. * Enter a new tag name to create a new tag. 5. Select **Apply**. ### Related information * [Managing applications](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications) * [Scopes](broken://pages/2OEAUmhkBPZnqcSIPLGU) * [Applications](broken://pages/g9htknA2LyUsOVD8onnT) # Application Owners Application owners identify the people responsible for an application. Assigning owners helps establish accountability and enables ownership-based filtering, reporting, workflows, and application scopes. An application can have multiple owners with different responsibilities. ### Owner roles You can assign the following owner roles:
RoleDescription
DevResponsible for developing and maintaining the application's code.
BusinessResponsible for the application from a business perspective.
SecurityResponsible for the application's security posture and remediation activities.
WatcherReceives notifications and can monitor the application without being responsible for remediation.
### Assign application owners You can assign owners to one or more applications simultaneously. **To assign application owners:** 1. Go to **Applications**. 2. Select one or more applications. 3. Select **Assign Owner**.
4. Select the required owner role. 5. Do one of the following: * In the **Select to change Dev owners** section, elect one or more existing users, Or * In the **Add New Owner** section, enter the owner's name and email address, and then select **Add**. 6. Select **Save**. ### Best practices * Assign at least one owner to every application. * Assign owners according to their responsibilities. * Keep ownership information up to date when responsibilities change. * Use owners consistently when defining application scopes. ### Related information * [Managing applications](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications) * [Scopes](broken://pages/2OEAUmhkBPZnqcSIPLGU) * [Applications](broken://pages/g9htknA2LyUsOVD8onnT) # Application Scan Settings You can configure scan settings for one or more repository applications before starting a scan. Scan settings allow you to specify which branch OX scans for each selected repository application. By default, OX scans the repository's default branch. If you configure a different branch, OX scans only the selected branch. > **Note:** The Application Scan Settings action is available only when[ Multi-Branch Scanning](/scan-and-analyze-with-ox/scanning/multi-branch-support) is disabled. If Multi-Branch Scanning is enabled, configure the branches to scan in the source control connector settings. **To configure application scan settings:** 1. Go to **Applications**. 2. Select one or more repository applications. 3. Select **Application Scan Settings**.
4. In **Branch Name**, specify the branch to scan. 5. Select **Apply**. The configured branch is used the next time the selected applications are scanned. ### Related information * [Scan Selected Repositories](/scan-and-analyze-with-ox/scanning/multi-branch-support) * [Managing Applications](/scan-and-analyze-with-ox/analyzing-scan-results/applications/managing-applications) * [Applications](broken://pages/g9htknA2LyUsOVD8onnT) # Application Details The Application details page provides a comprehensive view of a single application. It combines security findings, repository information, inventory, ownership, and deployment data to help you understand the application's security posture and investigate issues in context. Use this page to: * Review the application's security findings. * Understand the technologies and assets associated with the application. * Identify application ownership and activity. * Explore the application's deployment flow. * Configure application-specific settings.
The Application details page includes the following sections: * [**Explore**:](/scan-and-analyze-with-ox/analyzing-scan-results/applications/application-details/application-details-explore-tab) Provides an overview of the application's security posture, inventory, and deployment. * [**Owners & Activity**:](/scan-and-analyze-with-ox/analyzing-scan-results/applications/application-details/application-details-owners-and-activity-tab) Displays application ownership information and recent activity. * **Containers**: Lists the container images associated with the application. * [**More Info**:](/scan-and-analyze-with-ox/analyzing-scan-results/applications/application-details/application-details-more-info-tab) Displays additional metadata collected for the application. ### Header The header provides a quick summary of the application and quick access to related resources. | Item | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Application name** | Name of the application. | | **Repository provider** | Source control provider associated with the application, such as GitHub or GitLab. | | **Issues** | Total number of active issues detected for the application. Select the value to open the Active Issues page filtered for this application. | | **Business Priority** | Business priority assigned to the application. | | **Source Link** | Opens the application repository in the source control provider. | # Application Details: Explore tab The Explore tab provides an overview of the application's security posture, inventory, technologies, and deployment. Use this tab to quickly understand the application, review its security findings, and navigate to related assets.
## Categories The Categories section summarizes the application's findings by security category. Each category displays: * The highest detected severity. * The total number of findings. * The distribution of findings by severity. Select View *n* Issues to open the Active Issues page filtered for the current application. The available categories depend on the security capabilities enabled for your organization. ## Application information The application information panel displays general information about the application. | Field | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------ | | **Type** | Type of application or repository. | | **Access Level** | Indicates whether the repository is public or private. | | **Analyzed Branch** | Branch currently analyzed by OX. | | **Latest Code Change** | Time since the latest code change detected in the repository. | | **First Seen in OX** | Date when OX first discovered the application. | | **OX in Pipeline** | Indicates whether pipeline scanning is enabled for the application. | | **Languages** | Programming languages detected in the application. Select the field to view the language distribution. | ## Inventory The Inventory section summarizes the assets and components discovered for the application. Select an inventory item to open the corresponding page or view additional information. | Item | Description | | ------------------------- | --------------------------------------------------------------- | | **Developers** | Developers associated with the application. | | **Files** | Files discovered in the repository. | | **Commits** | Commits analyzed by OX. | | **Artifacts** | Container artifacts associated with the application. | | **Dependencies (Images)** | Container image dependencies associated with the application. | | **Dependencies (Code)** | Code dependencies identified during analysis. | | **SaaS Items** | SaaS applications and services associated with the application. | | **APIs** | APIs discovered for the application. | ## Tags The Tags section displays the tags assigned to the application. Tags help organize applications and can be used for filtering, reporting, and defining scopes. Select the Edit icon to add or remove tags assigned to the application. ## Application Flow The Application Flow visualizes the application's software supply chain, from the source repository to the deployed runtime resources. The flow is built automatically from the integrations connected to OX and may include: * Source control repositories * CI/CD platforms * Container registries * Cloud providers * Kubernetes environments Each node displays the connected resource and, when applicable, the number of associated assets. Select a node to view additional details about that resource. The Application Flow helps you understand how the application moves through your development and deployment pipeline and provides quick navigation between related assets. # Application Details: Owners & Activity tab The Owners & Activity tab provides information about the people responsible for the application, the technologies used, and repository activity and metadata. Use this tab to identify application owners, understand the application's technology stack, and review repository information.
## Owners The Owners section lists the users responsible for different aspects of the application. You can assign one or more owners to each ownership role. | Owner type | Description | | ------------------- | ------------------------------------------------------------------------------ | | **Business Owners** | Responsible for the business aspects of the application. | | **Security Owners** | Responsible for the application's security posture and remediation activities. | | **Dev Owners** | Responsible for developing and maintaining the application. | | **Watchers** | Users who want to monitor the application without being assigned ownership. | Select Add owner to assign an owner to the selected role. ## Languages The Languages section displays the programming languages and file types detected in the application. For each language, OX displays: * The percentage of the repository represented by the language. * A visual distribution of the application's technology stack. Use this information to quickly understand the primary technologies used by the application. ## Activity The Activity section displays repository metadata and activity information collected from the connected source control provider. | Field | Description | | ---------------------- | -------------------------------------------------------------------------- | | **Creator** | User who created the repository. | | **Type** | Repository type. | | **Access Level** | Indicates whether the repository is public or private. | | **Watchers** | Number of users watching the repository. | | **Tags** | Repository tags imported from the source control provider, when available. | | **YAMLs** | Number of YAML files detected in the repository. | | **Repo Size** | Repository size. | | **Push Events** | Number of push events detected, when available. | | **Pull Requests** | Number of pull requests associated with the repository, when available. | | **Branches** | Number of branches in the repository. | | **Downloads** | Indicates whether repository downloads are enabled. | | **Forks** | Number of repository forks. | | **Analyzed Branch** | Branch currently analyzed by OX. | | **Creation Date** | Date when the repository was created. | | **Latest Code Change** | Date of the most recent code change detected in the repository. | | **First Seen in OX** | Date when OX first discovered the application. | | **OX in Pipeline** | Indicates whether pipeline scanning is enabled for the application. | | **Latest Scan Type** | Type of the most recent scan performed for the application. | Some fields may not be available for all source control providers or repositories. When information is unavailable, OX displays no value for the corresponding field. # Application Details: More Info tab The More Info tab provides additional insights into the application's security posture and findings. Use this tab to review findings by attack technique, monitor issue trends, and analyze issue statistics. ### OSC\&R The OSC\&R section organizes application findings according to the Open Source Cybersecurity Reference (OSC\&R) framework.
Findings are grouped by attack tactic, making it easier to understand how vulnerabilities relate to different stages of the software supply chain attack lifecycle. Each tactic displays: * The number of techniques for which findings were identified. * The OSC\&R techniques associated with the application. * The number of findings for each severity level within each technique. Select a technique to view the related findings. ### Issue Trends The Issue Trends chart shows how the number of issues has changed over time.
The chart displays issues by severity, allowing you to identify trends such as: * Increasing or decreasing numbers of findings. * Changes in the application's overall security posture. * The impact of remediation efforts over time. Use this chart to monitor the application's security progress across successive scans. ### Issue Statistics The Issue Statistics section summarizes the application's findings from multiple perspectives.
Each widget groups findings by a different attribute. The available widgets include: | Widget | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------ | | **Category** | Distribution of findings by security category, such as Code Security, Open Source Security, or Container Security. | | **Severity** | Distribution of findings by severity level. | | **Issue Owner** | Distribution of findings by the assigned issue owner. | | **Source Tool** | Distribution of findings by the OX scanning capability or integrated source that identified them. | Select a value within a widget to further analyze the corresponding findings. # Active Issues The Active Issues page is your central workspace for monitoring and managing security, compliance, and configuration risks detected across your connected applications and infrastructure. From here, you can prioritize critical findings, assign ownership, and track progress over time.
The main parts of the Active Issues page are the [issues table](#issues-table) and the [filters](#filtering-issues). You can open [each issue to view the details and perform actions](/scan-and-analyze-with-ox/analyzing-scan-results/issues/issue-details). ## Issues Table The Issues table is the main working area of the Active Issues page. It presents all detected security, compliance, and configuration issues across your connected applications and infrastructure. Most column headers support sorting. You can select a column header, such as Severity, SLA, or First Seen, to reorder the table and surface the most critical or oldest issues at the top of the list. The following table explains the purpose and behavior of each column in the issues table.
ColumnDescription
SelectionUse the checkbox at the beginning of each row to select one or more issues. Selection enables bulk actions from the page toolbar, such as assigning owners or applying workflow actions.
#Displays the row number in the current table view. The numbering reflects the current sort and filter state rather than a permanent issue identifier.
SeverityIndicates the risk level assigned to the issue, such as Critical. Severity helps you prioritize remediation based on potential impact and exposure.
CategoryShows the security domain or scan type that detected the issue, such as Open Source Security, Container Security, SBOM, or Infrastructure as Code Scan. This column helps you quickly understand the technical context of the finding.
NameProvides a short, descriptive title for the issue. The name usually includes the affected component and a brief explanation of the risk, such as a vulnerable dependency, an exposed resource, or a misconfiguration. Select the issue name to open the issue details page, where you can review technical evidence, remediation guidance, and activity history.
SLADisplays the service level agreement status for the issue. This value shows how much time has passed relative to the defined remediation target. Positive values, such as +8mo or +2y, indicate how long the issue has exceeded its SLA.
ApplicationIdentifies the application, repository, or environment where the issue was detected. This value reflects the connection source, such as a GitHub repository, container image, or cloud resource. Select the application name to navigate to the related asset or integration context.
Issue OwnerShows the user currently assigned to the issue. Ownership indicates who is responsible for reviewing and coordinating remediation. If no owner is assigned, this column may be empty or display a placeholder, depending on your organization settings.
First SeenIndicates when OX first detected this issue. This value helps you understand how long the risk has existed in your environment.
CountDisplays how many times this issue appears across assets or scans. A higher count can indicate a systemic problem, such as a vulnerable dependency used in multiple projects.
ActionsProvides a menu for issue-level actions. Use this column to perform tasks such as assigning an owner, updating status, or triggering workflow steps, depending on your organization configuration.
### Typical workflow 1. Sort by Severity or [SLA](/exclusions-and-sla/scope-policy-and-sla-compliance/enforcing-sla) to identify the most urgent issues. 2. Select an issue name to review technical [details and remediation guidance](/scan-and-analyze-with-ox/analyzing-scan-results/issues/issue-details). 3. Assign an[ Issue Owner](/scan-and-analyze-with-ox/analyzing-scan-results/issues/assigning-issue-owners) if one is not already set. 4. Track progress over time using the First Seen and SLA columns to verify that issues are being addressed within your organization’s targets. ## Filtering issues The Active Issues page provides a filter sidebar for narrowing the issue list to the work that matters to you. Filters are split into a primary set (always visible) and an **Additional filters (45)** section that expands to reveal more granular options. ### Primary filters
FilterWhat it filters
ApplicationIssues belonging to a specific application or repository.
SeverityIssues by severity (Appox, Critical, High, Medium, Low, Info).
Severity FactorIssues by the contextual severity factor that influenced their final score (for example, Active Secret in Exposed Cloud Asset).
CategoryIssues by category, such as secrets, misconfiguration, or vulnerabilities.
Issue NameIssues by their canonical issue name.
PolicyIssues triggered by a specific OX policy.
ActionsIssues by the action taken on them (for example, remediated, ignored, snoozed).
App TagIssues on applications that carry a given tag.
SLAIssues by SLA status (within SLA, breached, soon to breach).
Code-to-Cloud ExposureIssues that have a code-to-cloud exposure path.
Exposure by APIIssues exposed via an API.
### Additional filters Click **Additional filters (45)** to expand the full filter list. The filters below cover status history, ownership, integrations, infrastructure, compliance, and artifact details.
FilterWhat it filters
Severity Change LogIssues whose severity has changed, based on the change log.
Issue Status Over TimeIssues by status at a given point in time.
Issue Status vs Last ScanIssues by how their status compares to the previous scan.
Severity Before PrioritizationIssues by their original (pre-prioritization) severity.
Severity ReprioritizedIssues whose severity was changed by OX prioritization.
Application SourceIssues by the source of the application (for example, Git provider or registry).
Issue OwnerIssues by assigned owner.
Source ToolIssues by the OX source or scanner that produced them.
OSC&R TacticIssues by OSC&R attack tactic (for example, Initial Access).
OSC&R TechniqueIssues by OSC&R technique (for example, T0112: Compromised token).
Compliance StandardIssues by compliance framework (for example, SOC2, PCI_DSS, ISO27001).
Compliance ControlIssues by specific compliance control.
CVEIssues associated with a specific CVE.
DAST URLIssues found at a specific DAST-scanned URL.
CVSS Base ScoreIssues by CVSS base score (or score range).
CWEIssues by CWE classification.
LanguagesIssues by the programming language of the affected code.
Vulnerable LibraryIssues tied to a specific vulnerable library.
Files With IssuesIssues by the file they live in.
Analyzed BranchIssues found on a specific scanned branch.
Business PriorityIssues by the business priority of the affected app.
Registry NameIssues found in a specific container or artifact registry.
Registry TypeIssues by registry type (for example, ECR, GCR, Docker Hub).
Artifact ImageIssues by the specific artifact image.
Registry RegionIssues by registry region.
Registry Account IdIssues by the registry's account ID.
Kubernetes ClusterIssues affecting a specific Kubernetes cluster.
Kubernetes NamespaceIssues in a specific Kubernetes namespace.
Kubernetes LabelIssues with a specific Kubernetes labels assigned to Kubernetes resources. Labels are inherited from the Kubernetes environment and help you find issues or artifacts associated with workloads that have specific Kubernetes labels. Supports selecting one or more label values.
Cloud RegionIssues by cloud region.
Cloud AccountIssues by cloud account.
Cloud ServiceIssues by cloud service (for example, S3, EC2, Lambda).
Cloud ResourceIssues by specific cloud resource.
Artifact OS ImageIssues by the artifact's underlying OS image.
Artifact Base ImageIssues by the artifact's base image.
Artifact SHAIssues by artifact SHA digest.
Artifact PathIssues by path within the artifact.
First SeenIssues by when they were first detected.
Connection NameIssues by the OX connection (integration) that detected them.
Ticket StatusIssues by external ticket status (for example, in Jira).
Commit DateIssues by the commit date of the affected code.
Business UnitIssues by business unit.
Rule IDIssues by the specific rule ID that triggered them.
CSPM Enhanced IssuesCSPM issues that have been enriched with additional context.
Triage StatusIssues by triage status.
Issues Without …Issues that are missing a specified attribute (for example, without an owner or without a ticket).
Use the **Search filters** box at the top of the sidebar to jump directly to any filter by name. # Issue Details The issue details page provides a single, complete view of a detected issue, its identity, severity, ownership, supporting evidence, and the actions you can take to resolve or dismiss it.
The page contains the following parts: * [Issue header](#issue-header) * [Explore](/scan-and-analyze-with-ox/analyzing-scan-results/issues/explore) * [Dev Explore](/scan-and-analyze-with-ox/analyzing-scan-results/issues/issue-details-dev-explore) * [Context](/scan-and-analyze-with-ox/analyzing-scan-results/issues/issue-details-context) * [Sensitive Data](/scan-and-analyze-with-ox/analyzing-scan-results/issues/issue-details-sensitive-data) * [Artifacts and Artifact Files](/scan-and-analyze-with-ox/analyzing-scan-results/issues/issue-details-artifacts-and-artifact-files) * [Commits](/scan-and-analyze-with-ox/analyzing-scan-results/issues/issue-details-commits) * [Extra Info](/scan-and-analyze-with-ox/analyzing-scan-results/issues/issue-details-extra-info) * [Issue actions](/scan-and-analyze-with-ox/analyzing-scan-results/issues/issue-details-extra-info) ## Issue Header The issue header provides a quick summary of the issue, including its type, severity, detection source, and ownership context.
You can use this section to immediately understand what the issue is and how critical it is. Example: `S3 · Publicly Accessible · AWS · Internet Exposed · Bucket Has Data` Each part represents a different aspect of the issue:
ElementDescription
S3The affected service or asset type.
Publicly AccessibleThe core issue or misconfiguration detected.
AWSThe cloud provider where the issue exists.
Internet ExposedIndicates that the resource is accessible from the public internet.
Bucket Has DataProvides additional context about the resource state, increasing the risk level.
This structure helps you quickly understand what the issue is, where it exists, and why it is risky. | Field | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------- | | Severity | Indicates the risk level of the issue (for example, Apocalypse). Higher severity requires faster remediation. | | Trend indicator | Shows whether the issue severity or risk trend is increasing or decreasing. | | Context type | Indicates the context category of the issue (for example, Cloud Context). | | Owner | The details f the issue owner. | | Application / Project | The application or project associated with the issue. | ## Issue actions The action bar allows you to take immediate action on an issue directly from the Issue details page.
Use these actions to manage the issue lifecycle, collaborate with your team, and trigger remediation workflows. | Action | Description | | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | [Exclude](/exclusions-and-sla/scope-policy-and-sla-compliance/exclusions) | Excludes the issue from active tracking. Use this when the issue is not relevant or accepted as risk. | | [Report false positive issue](/scan-and-analyze-with-ox/analyzing-scan-results/issues/reporting-false-positive-actions) | Marks the issue as a false positive. | | [Add comments](/ticketing-and-messaging/ticket-management/jira/page-1) | Adds a comment to the issue for collaboration or documentation. | | [Send a message to Slack](/ticketing-and-messaging/messaging/slack) | Sends the issue details to a configured Slack channel. | | [More options](#additional-actions) | Opens additional actions for advanced issue management. | | [Create ticket](/ticketing-and-messaging/ticket-management) | Creates a ticket in your configured ticketing system for remediation tracking. | ### Additional actions The **More options** menu provides additional actions:
ActionDescription
Copy link to issueCopies a direct link to the issue.
Start ChatGPTOpens ChatGPT with context about the issue.
View Code FixDisplays suggested remediation in code form, when available.
Jira actionsOpens Jira-related actions for the issue.
Snooze issueTemporarily hides the issue until a selected time.
Make app irrelevantMarks the related application as irrelevant for this issue.
Disable policyDisables the policy that generated the issue.
View/Edit policyOpens the policy configuration.
Change severityUpdates the severity level of the issue.
Change issue ownerAssigns or updates the issue owner.
SLA actionsOpens SLA-related actions for the issue.
--- [Next Page](/llms-full.txt/1)