# Deploy hooks for Claude Code Source: https://docs.endorlabs.com/agent-governance/claude-code/index Install Endor Labs hooks for Claude Code on macOS, Linux, and Windows developer machines to capture session, prompt, and tool events. Endor Labs hooks for Claude Code send a structured event for every session, user prompt, tool call, shell command, and file operation. The hook also enforces your Coding Agent Governance policies locally before each action reaches the agent. ## Before you begin Confirm the following requirements before you install the hook: * An admin has completed the [prerequisites](/agent-governance/prerequisites), including creating an API key with the **AI Audit User** role. * The target machine runs macOS, Linux, or Windows with Claude Code installed. * [endorctl](/setup-deployment/cli) is on `PATH`. This applies to the hand-written configuration below. A generated configuration installs and updates endorctl automatically at session start. Do not export `ENDOR_TOKEN` in the environment that launches Claude Code. Hooks authenticate with the API key and secret only, and on older versions of endorctl the extra token triggered a mixed-authentication error that blocked `endorctl ai-audit`. Prefer generating this file over maintaining it by hand. The [in-browser generator](/agent-governance/mdm-deployment#generate-a-configuration-in-your-browser) assembles `settings.json` (or a macOS configuration profile) from the [mdm-scripts repository](https://github.com/endorlabs/mdm-scripts/tree/main/agent-governance) sources, and adds a bootstrap that installs and updates endorctl at session start. Claude Code reads its credentials and namespace from the `env` block in `settings.json`, so the configuration is self-contained. Replace the placeholder values in `env` with your namespace and an API key issued for the **AI Audit User** role. ```json expandable theme={null} { "env": { "ENDOR_API": "https://api.endorlabs.com", "ENDOR_NAMESPACE": "", "ENDOR_API_CREDENTIALS_KEY": "", "ENDOR_API_CREDENTIALS_SECRET": "", "ENDOR_AI_AUDIT_CACHE_ENABLED": "true" }, "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit claudecode" } ] } ], "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit claudecode" } ] } ], "PreToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit claudecode" } ] } ], "PostToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit claudecode" } ] } ], "PostToolUseFailure": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit claudecode" } ] } ], "ConfigChange": [ { "hooks": [ { "type": "command", "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit claudecode" } ] } ], "SessionEnd": [ { "hooks": [ { "type": "command", "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit claudecode" } ] } ] } } ``` ## Install for one developer Use this for a single-machine trial or a personal install. 1. Open `~/.claude/settings.json` in a text editor. Create the file if it does not exist. 2. Paste the configuration shown in [Before you begin](#before-you-begin) under the `hooks` key. Merge with any existing `hooks` entries, because Claude Code does not deduplicate handlers across configurations. 3. Save the file and restart any active Claude Code session. ## Install on a managed fleet Claude Code reads enterprise hooks from a managed settings file: `/Library/Application Support/ClaudeCode/managed-settings.json` on macOS, or `/etc/claude-code/managed-settings.json` on Linux. Use your MDM, such as Jamf, Intune, Kandji, or JumpCloud, to deliver that file to each managed machine. The `env` block in the configuration above carries the Endor Labs credentials, so you don't need a separate shell setup. On macOS, environment variables set in `~/.zshrc` reach apps launched from a terminal but not apps launched from Spotlight. Ship the variables through your MDM payload (for example, a `launchctl setenv` profile or an `~/.zprofile` snippet) for full coverage. If your MDM's deployment script rejects the inline JSON payload, encode the configuration in Base64 in the script, and decode it on the target machine. This avoids the quoting and escaping issues that some MDMs introduce when publishing JSON. ## Per-repository overrides Add `/.claude/settings.json` and commit it. Repository hooks layer on top of user and enterprise hooks and let security-sensitive projects extend the configuration. For developer-local additions outside source control, use `/.claude/settings.local.json`. ## Claude Code hook events used by Coding Agent Governance The table lists every event the hook processes. Claude Code events outside this set, such as `Stop`, `PermissionRequest`, and `SubagentStart`, are accepted and ignored if a configuration registers them, so an older configuration keeps working but those events record nothing. The `PreToolUse` hook fails open. If the hook itself errors out, Claude Code allows the tool call rather than blocking it and keeps working. The usual cause is a missing binary. An unreadable local policy cache does not disable enforcement, because the hook falls back to the built-in system policies. A successfully evaluated **Block** policy still stops the tool call. ## Tune the hook For an audit-only rollout, set `ENDOR_AI_AUDIT_NO_BLOCKING=true` in the hook environment. [endorctl ai-audit](/developers-api/cli/commands/ai-audit) then downgrades every `Block` action to `Alert` at evaluation time. For Cursor, set it in the shell that launches the IDE. For Claude Code, set it in the `env` block of `settings.json`. Policies still record violations under **Policy Violations**, but the hook never denies a . Use this to seed a new policy without interrupting developers, then unset the variable when you're ready to enforce. Any value parsable as a Go bool (such as `true`, `1`, or `t`) turns the option on. Unset, empty, or unparseable values keep enforcement on. ## Verify hooks are firing 1. Start a session in and ask the agent to run a benign shell command, such as `ls`. 2. Select **Agent Governance** from the left sidebar, then select **Workstation Inventory**. 3. Confirm the developer's row shows a recent value under **Last Active**. If no row appears, see [Troubleshoot a quiet machine](#troubleshoot-a-quiet-machine). ## What developers see when a policy fires When a policy with the **Block** action matches an event, the hook returns a deny response to . stops the and surfaces the **User Message** to the developer. The agent receives a deny response that carries the **User Message**, explains that a governance policy denied the action, and tells the agent not to work around the block. When a policy with the **Ask Permission** action matches, the hook returns an ask response. pauses and asks the developer to confirm or deny before the agent proceeds. When a policy with the **Alert** action matches, the hook allows the action to proceed. Endor Labs records the event under **Policy Violations** for your security team to review. ## Troubleshoot a quiet machine Run these checks if a developer's actions never appear under **Workstation Inventory** or **Policy Violations**: * Confirm the developer has started at least one session. With the event cache enabled, the hook batches events and flushes them within about 30 seconds of hook activity, and fully at session start and end, so inventory **Sessions**, **Last Active**, and counts can lag the newest actions by that interval. * Hook errors fail open. If the hook cannot run or reach the Endor Labs API, allows the . The event is missing from inventory rather than surfacing an error. The remaining checks rule out the common causes. * Confirm endorctl is on `PATH` in the environment that runs the hook. The hook fails silently if the binary is not found. Run `endorctl version` from the same shell to verify. * Confirm only one endorctl installation is active. If `endorctl ai-audit` fails with `Failed with non-blocking status code: No stderr output`, conflicting installations are the likely cause, such as an `npx`-provisioned endorctl alongside a Homebrew install. Keep one installation method per machine, remove the others, then run `endorctl version` to confirm. * Confirm `ENDOR_API`, `ENDOR_NAMESPACE`, `ENDOR_API_CREDENTIALS_KEY`, and `ENDOR_API_CREDENTIALS_SECRET` are set for the process that runs the hook. Cursor reads them from the shell that launched it. Claude Code reads them from the `env` block in `settings.json`. * Confirm `ENDOR_TOKEN` is not also exported alongside your Coding Agent Governance API key credentials in the hook environment. Hooks rely only on `ENDOR_API_CREDENTIALS_KEY` and `ENDOR_API_CREDENTIALS_SECRET`. `ENDOR_TOKEN` is redundant and, on older versions of endorctl, triggered a mixed-authentication error that blocked `endorctl ai-audit`. * Confirm the API key has the **AI Audit User** role and has not expired. * Confirm the developer restarted after the hooks file changed. reads the configuration at session start. * Confirm the developer restarted after a policy edit. The local policy cache refreshes at session start. * Confirm the JSON file parses. A trailing comma silently disables every hook in the file. * Confirm the Endor Labs API is reachable from the environment that runs the hook. Network failures appear as gaps in the inventory. ## Next steps With hooks deployed, continue with the following pages: * See [Triage policy violations](/agent-governance/policy-violations) to set your daily review workflow. * See [Read the Coding Agent Governance overview](/agent-governance/overview) to track adoption and enforcement trends. # Deploy hooks for Codex Source: https://docs.endorlabs.com/agent-governance/codex/index Install Endor Labs hooks for the Codex CLI on macOS, Linux, and Windows developer machines to capture session, command, and file events. Endor Labs hooks for Codex send a structured event for every session, prompt, shell command, file patch, and MCP tool call the Codex CLI makes. The hook also enforces your Coding Agent Governance policies locally before each action runs. ## Before you begin Confirm the following requirements before you install the hook: * An admin has completed the [prerequisites](/agent-governance/prerequisites), including creating an API key with the **AI Audit User** role. * The target machine runs macOS, Linux, or Windows with the Codex CLI installed. * endorctl is on `PATH`. See [endorctl CLI](/setup-deployment/cli). * The shell that launches Codex has these environment variables set: * `ENDOR_API` (for example, `https://api.endorlabs.com`) * `ENDOR_NAMESPACE` * `ENDOR_API_CREDENTIALS_KEY` * `ENDOR_API_CREDENTIALS_SECRET` Do not export `ENDOR_TOKEN` in the environment that runs the hook. Hooks authenticate with the API key and secret only, and on older versions of endorctl the extra token triggered a mixed-authentication error that blocked `endorctl ai-audit`. Prefer generating this configuration over maintaining it by hand. The [in-browser generator](/agent-governance/mdm-deployment#generate-a-configuration-in-your-browser) assembles a Codex `requirements.toml` (or a macOS configuration profile) from the [mdm-scripts repository](https://github.com/endorlabs/mdm-scripts/tree/main/agent-governance) sources, and adds a bootstrap that installs and updates endorctl at session start. Codex reads hooks from the `[hooks]` table in `config.toml`. Use the following configuration. ```toml expandable theme={null} [[hooks.SessionStart]] [[hooks.SessionStart.hooks]] type = "command" command = "ENDOR_AI_AUDIT_CACHE_ENABLED=true endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit codex" [[hooks.UserPromptSubmit]] [[hooks.UserPromptSubmit.hooks]] type = "command" command = "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit codex" [[hooks.PreToolUse]] matcher = ".*" [[hooks.PreToolUse.hooks]] type = "command" command = "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit codex" [[hooks.PermissionRequest]] [[hooks.PermissionRequest.hooks]] type = "command" command = "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit codex" [[hooks.PostToolUse]] matcher = ".*" [[hooks.PostToolUse.hooks]] type = "command" command = "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit codex" [[hooks.Stop]] [[hooks.Stop.hooks]] type = "command" command = "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit codex" ``` Codex also accepts the same events in a sibling `hooks.json` file, and it runs both sources additively. Define each event in one place only, or the hook fires twice per event. ## Install for one developer Use this for a single-machine trial or a personal install. 1. Open `~/.codex/config.toml` in a text editor. Create the file if it does not exist. 2. Append the `[hooks]` configuration shown in [Before you begin](#before-you-begin). 3. Save the file and start a new Codex session. If `CODEX_HOME` is set, edit `config.toml` in that directory instead. ## Install on a managed fleet Codex reads system-managed configuration from a fixed directory per platform. Use your MDM, such as Jamf, Intune, Kandji, or JumpCloud, to deliver the hook configuration to each managed machine. Also deliver the four Endor Labs environment variables in the shell that launches Codex. * On macOS and Linux, deliver `/etc/codex/hooks.json`, or add the `[hooks]` table to `/etc/codex/requirements.toml`. Settings in `requirements.toml` take precedence over the other configuration layers. * On Windows, deliver `%ProgramData%\OpenAI\Codex\hooks.json` or `%ProgramData%\OpenAI\Codex\requirements.toml`. On macOS, environment variables set in `~/.zshrc` reach apps launched from a terminal but not apps launched from Spotlight. Ship the variables through your MDM payload (for example, a `launchctl setenv` profile or an `~/.zprofile` snippet) for full coverage. If your MDM's deployment script rejects the inline JSON payload, encode the configuration in Base64 in the script, and decode it on the target machine. This avoids the quoting and escaping issues that some MDMs introduce when publishing JSON. ## Per-repository overrides Add the `[hooks]` table to `/.codex/config.toml` and commit it. Repository hooks let security-sensitive projects extend the configuration. Codex loads repository configuration only after the developer trusts the project. A committed hook configuration takes effect once the project's `trust_level` is `trusted` in the developer's Codex configuration. ## Codex hook events used by Coding Agent Governance Enforcement hooks fail open. If the hook itself errors out, Codex allows the action rather than blocking it and keeps working. The usual cause is a missing binary. An unreadable local policy cache does not disable enforcement, because the hook falls back to the built-in system policies. A successfully evaluated **Block** policy still stops the action. Codex handles the **Ask Permission** action differently from other agents: * At `PreToolUse`, Codex honors only a deny response and cannot pause for approval. An **Ask Permission** policy fails closed and denies the call, carrying the ask message so the developer sees why. * At `PermissionRequest`, an **Ask Permission** policy defers to Codex's own approval prompt, which asks the developer directly. Only a **Block** policy denies the escalation outright. Codex reports file changes through its `apply_patch` tool. **File Access** policies match each file in the patch individually, and a `Write`, `Edit`, or `apply_patch` matcher all target the same tool. ## Tune the hook For an audit-only rollout, set `ENDOR_AI_AUDIT_NO_BLOCKING=true` in the hook environment. [endorctl ai-audit](/developers-api/cli/commands/ai-audit) then downgrades every `Block` action to `Alert` at evaluation time. For Cursor, set it in the shell that launches the IDE. For Claude Code, set it in the `env` block of `settings.json`. Policies still record violations under **Policy Violations**, but the hook never denies a . Use this to seed a new policy without interrupting developers, then unset the variable when you're ready to enforce. Any value parsable as a Go bool (such as `true`, `1`, or `t`) turns the option on. Unset, empty, or unparseable values keep enforcement on. ## Verify hooks are firing 1. Start a session in and ask the agent to run a benign shell command, such as `ls`. 2. Select **Agent Governance** from the left sidebar, then select **Workstation Inventory**. 3. Confirm the developer's row shows a recent value under **Last Active**. If no row appears, see [Troubleshoot a quiet machine](#troubleshoot-a-quiet-machine). ## What developers see when a policy fires When a policy with the **Block** action matches an event, the hook returns a deny response to . stops the and surfaces the **User Message** to the developer. The agent receives a deny response that carries the **User Message**, explains that a governance policy denied the action, and tells the agent not to work around the block. When a policy with the **Ask Permission** action matches, the hook returns an ask response. pauses and asks the developer to confirm or deny before the agent proceeds. When a policy with the **Alert** action matches, the hook allows the action to proceed. Endor Labs records the event under **Policy Violations** for your security team to review. ## Troubleshoot a quiet machine Run these checks if a developer's actions never appear under **Workstation Inventory** or **Policy Violations**: * Confirm the developer has started at least one session. With the event cache enabled, the hook batches events and flushes them within about 30 seconds of hook activity, and fully at session start and end, so inventory **Sessions**, **Last Active**, and counts can lag the newest actions by that interval. * Hook errors fail open. If the hook cannot run or reach the Endor Labs API, allows the . The event is missing from inventory rather than surfacing an error. The remaining checks rule out the common causes. * Confirm endorctl is on `PATH` in the environment that runs the hook. The hook fails silently if the binary is not found. Run `endorctl version` from the same shell to verify. * Confirm only one endorctl installation is active. If `endorctl ai-audit` fails with `Failed with non-blocking status code: No stderr output`, conflicting installations are the likely cause, such as an `npx`-provisioned endorctl alongside a Homebrew install. Keep one installation method per machine, remove the others, then run `endorctl version` to confirm. * Confirm `ENDOR_API`, `ENDOR_NAMESPACE`, `ENDOR_API_CREDENTIALS_KEY`, and `ENDOR_API_CREDENTIALS_SECRET` are set for the process that runs the hook. Cursor reads them from the shell that launched it. Claude Code reads them from the `env` block in `settings.json`. * Confirm `ENDOR_TOKEN` is not also exported alongside your Coding Agent Governance API key credentials in the hook environment. Hooks rely only on `ENDOR_API_CREDENTIALS_KEY` and `ENDOR_API_CREDENTIALS_SECRET`. `ENDOR_TOKEN` is redundant and, on older versions of endorctl, triggered a mixed-authentication error that blocked `endorctl ai-audit`. * Confirm the API key has the **AI Audit User** role and has not expired. * Confirm the developer restarted after the hooks file changed. reads the configuration at session start. * Confirm the developer restarted after a policy edit. The local policy cache refreshes at session start. * Confirm the JSON file parses. A trailing comma silently disables every hook in the file. * Confirm the Endor Labs API is reachable from the environment that runs the hook. Network failures appear as gaps in the inventory. ## Next steps With hooks deployed, continue with the following pages: * See [Triage policy violations](/agent-governance/policy-violations) to set your daily review workflow. * See [Read the Coding Agent Governance overview](/agent-governance/overview) to track adoption and enforcement trends. # Deploy hooks for GitHub Copilot Source: https://docs.endorlabs.com/agent-governance/copilot/index Install Endor Labs hooks for the GitHub Copilot CLI and VS Code agent mode to capture session, command, and file events. Endor Labs hooks for GitHub Copilot send a structured event for every session, prompt, shell command, file operation, and MCP tool call. The hook covers the Copilot CLI and VS Code agent mode, and enforces your Coding Agent Governance policies locally before each action runs. Copilot on github.com, such as web chat and pull request reviews, runs on GitHub's infrastructure and is out of scope. ## Before you begin Confirm the following requirements before you install the hook: * An admin has completed the [prerequisites](/agent-governance/prerequisites), including creating an API key with the **AI Audit User** role. * The target machine runs macOS, Linux, or Windows with the Copilot CLI or VS Code with Copilot installed. * endorctl is on `PATH`. See [endorctl CLI](/setup-deployment/cli). * The environment that launches Copilot has these environment variables set: * `ENDOR_API` (for example, `https://api.endorlabs.com`) * `ENDOR_NAMESPACE` * `ENDOR_API_CREDENTIALS_KEY` * `ENDOR_API_CREDENTIALS_SECRET` Do not export `ENDOR_TOKEN` in the environment that runs the hook. Hooks authenticate with the API key and secret only, and on older versions of endorctl the extra token triggered a mixed-authentication error that blocked `endorctl ai-audit`. Use the following hook configuration. The `bash` command runs on macOS and Linux, and the `powershell` command runs on Windows. ```json expandable theme={null} { "version": 1, "hooks": { "SessionStart": [ { "type": "command", "bash": "endorctl ai-audit copilot", "powershell": "endorctl ai-audit copilot", "timeoutSec": 30 } ], "UserPromptSubmit": [ { "type": "command", "bash": "endorctl ai-audit copilot", "powershell": "endorctl ai-audit copilot", "timeoutSec": 30 } ], "PreToolUse": [ { "type": "command", "bash": "endorctl ai-audit copilot", "powershell": "endorctl ai-audit copilot", "timeoutSec": 30 } ], "PostToolUse": [ { "type": "command", "bash": "endorctl ai-audit copilot", "powershell": "endorctl ai-audit copilot", "timeoutSec": 30 } ], "PostToolUseFailure": [ { "type": "command", "bash": "endorctl ai-audit copilot", "powershell": "endorctl ai-audit copilot", "timeoutSec": 30 } ], "Stop": [ { "type": "command", "bash": "endorctl ai-audit copilot", "powershell": "endorctl ai-audit copilot", "timeoutSec": 30 } ], "SessionEnd": [ { "type": "command", "bash": "endorctl ai-audit copilot", "powershell": "endorctl ai-audit copilot", "timeoutSec": 30 } ] } } ``` Use the capitalized event names shown above on both surfaces. They make the Copilot CLI include the event name in the hook payload, so the same command works everywhere. The `timeoutSec` value is the ceiling Copilot applies to each hook invocation. endorctl limits itself to 5 seconds per invocation regardless, and fails open when the limit is reached, so the hook never holds an action for the full 30 seconds. ## Install for one developer Use this for a single-machine trial or a personal install. Personal hooks apply to the Copilot CLI. 1. Open `~/.copilot/hooks/endor.json` in a text editor. Create the file and directory if they do not exist. 2. Paste the configuration shown in [Before you begin](#before-you-begin). 3. Save the file and start a new Copilot session. If `COPILOT_HOME` is set, create the file under that directory instead. ## Install for a repository Repository hooks apply to both the Copilot CLI and VS Code agent mode, so they are the lever for covering VS Code users. Add `/.github/hooks/endor.json` with the same configuration and commit it. ## Install on a managed fleet Copilot has no system-wide hooks path. Use your MDM, such as Jamf, Intune, Kandji, or JumpCloud, to deliver `~/.copilot/hooks/endor.json` and the four Endor Labs environment variables to each managed machine for CLI coverage. Cover VS Code agent mode by committing the repository-level file to the repositories your developers work in. On macOS, environment variables set in `~/.zshrc` reach apps launched from a terminal but not apps launched from Spotlight. Ship the variables through your MDM payload (for example, a `launchctl setenv` profile or an `~/.zprofile` snippet) for full coverage. If your MDM's deployment script rejects the inline JSON payload, encode the configuration in Base64 in the script, and decode it on the target machine. This avoids the quoting and escaping issues that some MDMs introduce when publishing JSON. ## Copilot hook events used by Coding Agent Governance Enforcement hooks fail open. If the hook itself errors out, Copilot allows the action rather than blocking it and keeps working. The usual cause is a missing binary. An unreadable local policy cache does not disable enforcement, because the hook falls back to the built-in system policies. A successfully evaluated **Block** policy still stops the action. On a policy match at `PreToolUse`, a **Block** policy denies the tool call. An **Ask Permission** policy prompts the developer in VS Code agent mode only. The Copilot CLI honors deny but not ask, so on CLI sessions an **Ask** policy lets the call proceed and records it, the same way **Alert** behaves. An **Alert** policy lets the call proceed and records it on both surfaces. Session start is not a blocking point for Copilot. A session-level policy match surfaces as a governance notice in the session instead. ## Tune the hook For an audit-only rollout, set `ENDOR_AI_AUDIT_NO_BLOCKING=true` in the hook environment. [endorctl ai-audit](/developers-api/cli/commands/ai-audit) then downgrades every `Block` action to `Alert` at evaluation time. For Cursor, set it in the shell that launches the IDE. For Claude Code, set it in the `env` block of `settings.json`. Policies still record violations under **Policy Violations**, but the hook never denies a . Use this to seed a new policy without interrupting developers, then unset the variable when you're ready to enforce. Any value parsable as a Go bool (such as `true`, `1`, or `t`) turns the option on. Unset, empty, or unparseable values keep enforcement on. ## Verify hooks are firing 1. Start a session in and ask the agent to run a benign shell command, such as `ls`. 2. Select **Agent Governance** from the left sidebar, then select **Workstation Inventory**. 3. Confirm the developer's row shows a recent value under **Last Active**. If no row appears, see [Troubleshoot a quiet machine](#troubleshoot-a-quiet-machine). ## What developers see when a policy fires When a policy with the **Block** action matches an event, the hook returns a deny response to . stops the and surfaces the **User Message** to the developer. The agent receives a deny response that carries the **User Message**, explains that a governance policy denied the action, and tells the agent not to work around the block. When a policy with the **Ask Permission** action matches, the hook returns an ask response. pauses and asks the developer to confirm or deny before the agent proceeds. When a policy with the **Alert** action matches, the hook allows the action to proceed. Endor Labs records the event under **Policy Violations** for your security team to review. ## Troubleshoot a quiet machine Run these checks if a developer's actions never appear under **Workstation Inventory** or **Policy Violations**: * Confirm the developer has started at least one session. With the event cache enabled, the hook batches events and flushes them within about 30 seconds of hook activity, and fully at session start and end, so inventory **Sessions**, **Last Active**, and counts can lag the newest actions by that interval. * Hook errors fail open. If the hook cannot run or reach the Endor Labs API, allows the . The event is missing from inventory rather than surfacing an error. The remaining checks rule out the common causes. * Confirm endorctl is on `PATH` in the environment that runs the hook. The hook fails silently if the binary is not found. Run `endorctl version` from the same shell to verify. * Confirm only one endorctl installation is active. If `endorctl ai-audit` fails with `Failed with non-blocking status code: No stderr output`, conflicting installations are the likely cause, such as an `npx`-provisioned endorctl alongside a Homebrew install. Keep one installation method per machine, remove the others, then run `endorctl version` to confirm. * Confirm `ENDOR_API`, `ENDOR_NAMESPACE`, `ENDOR_API_CREDENTIALS_KEY`, and `ENDOR_API_CREDENTIALS_SECRET` are set for the process that runs the hook. Cursor reads them from the shell that launched it. Claude Code reads them from the `env` block in `settings.json`. * Confirm `ENDOR_TOKEN` is not also exported alongside your Coding Agent Governance API key credentials in the hook environment. Hooks rely only on `ENDOR_API_CREDENTIALS_KEY` and `ENDOR_API_CREDENTIALS_SECRET`. `ENDOR_TOKEN` is redundant and, on older versions of endorctl, triggered a mixed-authentication error that blocked `endorctl ai-audit`. * Confirm the API key has the **AI Audit User** role and has not expired. * Confirm the developer restarted after the hooks file changed. reads the configuration at session start. * Confirm the developer restarted after a policy edit. The local policy cache refreshes at session start. * Confirm the JSON file parses. A trailing comma silently disables every hook in the file. * Confirm the Endor Labs API is reachable from the environment that runs the hook. Network failures appear as gaps in the inventory. ## Next steps With hooks deployed, continue with the following pages: * See [Triage policy violations](/agent-governance/policy-violations) to set your daily review workflow. * See [Read the Coding Agent Governance overview](/agent-governance/overview) to track adoption and enforcement trends. # Deploy hooks for Cursor Source: https://docs.endorlabs.com/agent-governance/cursor/index Install Endor Labs hooks for Cursor on macOS, Linux, and Windows developer machines to capture session, command, and file events. Endor Labs hooks for Cursor send a structured event for every session, prompt, MCP tool call, shell command, and file operation in the IDE. The hook also enforces your Coding Agent Governance policies locally before each action reaches the agent. ## Before you begin Confirm the following requirements before you install the hook: * An admin has completed the [prerequisites](/agent-governance/prerequisites), including creating an API key with the **AI Audit User** role. * The target machine runs macOS, Linux, or Windows with Cursor installed. * [endorctl](/setup-deployment/cli) is on `PATH`. This applies to the hand-written configuration below. A generated configuration installs and updates endorctl automatically at session start. * The shell that launches Cursor has these environment variables set: * `ENDOR_API` (for example, `https://api.endorlabs.com`) * `ENDOR_NAMESPACE` * `ENDOR_API_CREDENTIALS_KEY` * `ENDOR_API_CREDENTIALS_SECRET` Do not export `ENDOR_TOKEN` in the environment that runs the hook. Hooks authenticate with the API key and secret only, and on older versions of endorctl the extra token triggered a mixed-authentication error that blocked `endorctl ai-audit`. Prefer generating this file over maintaining it by hand. The [in-browser generator](/agent-governance/mdm-deployment#generate-a-configuration-in-your-browser) assembles `hooks.json` from the [mdm-scripts repository](https://github.com/endorlabs/mdm-scripts/tree/main/agent-governance) sources for macOS, Linux, and Windows, and adds a bootstrap that installs and updates endorctl at session start. Use the following `hooks.json` configuration. ```json expandable theme={null} { "version": 1, "hooks": { "sessionStart": [ { "command": "ENDOR_AI_AUDIT_CACHE_ENABLED=true endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ], "sessionEnd": [ { "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ], "beforeSubmitPrompt": [ { "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ], "preToolUse": [ { "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ], "postToolUse": [ { "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ], "postToolUseFailure": [ { "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ], "beforeShellExecution": [ { "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ], "beforeMCPExecution": [ { "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ], "afterMCPExecution": [ { "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ], "beforeReadFile": [ { "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ], "beforeTabFileRead": [ { "command": "endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor" } ] } } ``` ## Install for one developer Use this for a single-machine trial or a personal install. 1. Open `~/.cursor/hooks.json` in a text editor. Create the file if it does not exist. 2. Paste the configuration shown in [Before you begin](#before-you-begin). 3. Save the file and restart Cursor. ## Install on a managed macOS fleet Cursor reads enterprise hooks from `/Library/Application Support/Cursor/hooks.json`. Use your MDM, such as Jamf, Intune, Kandji, or JumpCloud, to deliver that file to each managed machine. Also set the four Endor Labs environment variables (`ENDOR_API`, `ENDOR_NAMESPACE`, `ENDOR_API_CREDENTIALS_KEY`, `ENDOR_API_CREDENTIALS_SECRET`) in the shell that launches Cursor. On macOS, environment variables set in `~/.zshrc` reach apps launched from a terminal but not apps launched from Spotlight. Ship the variables through your MDM payload (for example, a `launchctl setenv` profile or an `~/.zprofile` snippet) for full coverage. If your MDM's deployment script rejects the inline JSON payload, encode the configuration in Base64 in the script, and decode it on the target machine. This avoids the quoting and escaping issues that some MDMs introduce when publishing JSON. ## Per-repository overrides Add `/.cursor/hooks.json` and commit it. Workspace hooks layer on top of user hooks and let security-sensitive projects extend the configuration. ## Cursor hook events used by Coding Agent Governance The table lists every event the hook processes. Cursor events outside this set, such as `subagentStart`, `preCompact`, `afterShellExecution`, `afterFileEdit`, and `stop`, are accepted and ignored if a configuration registers them, so an older configuration keeps working but those events record nothing. Enforcement hooks fail open. If the hook itself errors out, the action runs anyway and Cursor keeps working. The usual cause is a missing binary. An unreadable local policy cache does not disable enforcement, because the hook falls back to the built-in system policies. A successfully evaluated **Block** policy still stops the action. ## Tune the hook For an audit-only rollout, set `ENDOR_AI_AUDIT_NO_BLOCKING=true` in the hook environment. [endorctl ai-audit](/developers-api/cli/commands/ai-audit) then downgrades every `Block` action to `Alert` at evaluation time. For Cursor, set it in the shell that launches the IDE. For Claude Code, set it in the `env` block of `settings.json`. Policies still record violations under **Policy Violations**, but the hook never denies a . Use this to seed a new policy without interrupting developers, then unset the variable when you're ready to enforce. Any value parsable as a Go bool (such as `true`, `1`, or `t`) turns the option on. Unset, empty, or unparseable values keep enforcement on. ## Verify hooks are firing 1. Start a session in and ask the agent to run a benign shell command, such as `ls`. 2. Select **Agent Governance** from the left sidebar, then select **Workstation Inventory**. 3. Confirm the developer's row shows a recent value under **Last Active**. If no row appears, see [Troubleshoot a quiet machine](#troubleshoot-a-quiet-machine). ## What developers see when a policy fires When a policy with the **Block** action matches an event, the hook returns a deny response to . stops the and surfaces the **User Message** to the developer. The agent receives a deny response that carries the **User Message**, explains that a governance policy denied the action, and tells the agent not to work around the block. When a policy with the **Ask Permission** action matches, the hook returns an ask response. pauses and asks the developer to confirm or deny before the agent proceeds. When a policy with the **Alert** action matches, the hook allows the action to proceed. Endor Labs records the event under **Policy Violations** for your security team to review. ## Troubleshoot a quiet machine Run these checks if a developer's actions never appear under **Workstation Inventory** or **Policy Violations**: * Confirm the developer has started at least one session. With the event cache enabled, the hook batches events and flushes them within about 30 seconds of hook activity, and fully at session start and end, so inventory **Sessions**, **Last Active**, and counts can lag the newest actions by that interval. * Hook errors fail open. If the hook cannot run or reach the Endor Labs API, allows the . The event is missing from inventory rather than surfacing an error. The remaining checks rule out the common causes. * Confirm endorctl is on `PATH` in the environment that runs the hook. The hook fails silently if the binary is not found. Run `endorctl version` from the same shell to verify. * Confirm only one endorctl installation is active. If `endorctl ai-audit` fails with `Failed with non-blocking status code: No stderr output`, conflicting installations are the likely cause, such as an `npx`-provisioned endorctl alongside a Homebrew install. Keep one installation method per machine, remove the others, then run `endorctl version` to confirm. * Confirm `ENDOR_API`, `ENDOR_NAMESPACE`, `ENDOR_API_CREDENTIALS_KEY`, and `ENDOR_API_CREDENTIALS_SECRET` are set for the process that runs the hook. Cursor reads them from the shell that launched it. Claude Code reads them from the `env` block in `settings.json`. * Confirm `ENDOR_TOKEN` is not also exported alongside your Coding Agent Governance API key credentials in the hook environment. Hooks rely only on `ENDOR_API_CREDENTIALS_KEY` and `ENDOR_API_CREDENTIALS_SECRET`. `ENDOR_TOKEN` is redundant and, on older versions of endorctl, triggered a mixed-authentication error that blocked `endorctl ai-audit`. * Confirm the API key has the **AI Audit User** role and has not expired. * Confirm the developer restarted after the hooks file changed. reads the configuration at session start. * Confirm the developer restarted after a policy edit. The local policy cache refreshes at session start. * Confirm the JSON file parses. A trailing comma silently disables every hook in the file. * Confirm the Endor Labs API is reachable from the environment that runs the hook. Network failures appear as gaps in the inventory. ## Next steps With hooks deployed, continue with the following pages: * See [Triage policy violations](/agent-governance/policy-violations) to set your daily review workflow. * See [Read the Coding Agent Governance overview](/agent-governance/overview) to track adoption and enforcement trends. # Endor Scores for Coding Agent Governance Source: https://docs.endorlabs.com/agent-governance/endor-score/index Understand the Endor Labs trust score for MCP servers and skills, including its scale, the dimensions it weighs, and the OWASP LLM Top 10 categories it covers. The Endor Score is the trust score Endor Labs publishes for two things in your Coding Agent Governance inventory: * **Skills** discovered on developer machines at session start * **MCP servers** your governed agents call The score lets you compare risk across items at a glance and decide which to authorize, restrict, or block. This page describes how Endor Labs computes it and what it covers. ## Score scale Every Endor Score is a number from `1` to `10` on a single dimension: **higher is safer**. A score of `1` means the evaluator found severe risk. A score of `10` means it found none. For MCP servers, the headline score is the minimum across the four scored categories (**Supply Chain and Provenance**, **Authentication and Authorization**, **Operational Hygiene**, and **Input Validation and Injection**) that actually executed a check. A category with no applicable checks does not pull the score down. ### Bands and risk levels For at-a-glance triage, the Coding Agent Governance overview and inventory show the numeric score. Skills fall into four bands based on their score: The **Skills** pie chart on the [Overview](/agent-governance/overview) page currently labels the **Caution** and **Safe** bands as **Suspicious** and **Approved**. The MCP Servers inventory also shows a categorical **risk band** derived from the numeric score, on the same cutoffs the skill bands use, so a low score reads as high risk. ## How MCP servers are scored The MCP evaluator runs a set of static checks against each server's configuration and published source across seven dimensions. The first four dimensions carry their own scores. The other three contribute findings and evidence without a per-dimension score. Each scored dimension reports its own `1`-`10` score and a short evidence string that lists the checks that fired in that category. Checks that need a live connection to the server never run, so dimensions score from source and configuration alone. Endor Labs re-scores a server when its configuration changes, for example a new command, endpoint, transport, or environment variable name. ### OWASP LLM Top 10 coverage The evaluator tags every MCP finding with the OWASP LLM Top 10 category it represents, so a low score traces back to a recognized risk class. The MCP evaluator covers these categories: ## How skills are scored An Endor Labs backend large-language-model workflow scores skills by reading the `SKILL.md` content the hook discovers. The workflow produces a `1`-`10` score on four dimensions. The overall skill score is the minimum of the four dimension scores. Each dimension carries its own evidence string explaining the score. Scoring re-runs when the `SKILL.md` content hash changes, so Endor Labs re-evaluates an edit to a previously approved skill automatically. The **Endor Score Factors** side panel on a skill's detail drawer shows the verdict: the overall score and risk band, the four dimension scores, and an expandable evidence row per dimension. In this example, a skill that presents as a harmless notes summarizer lands in **Caution** because its bundle carries scripts the evaluator cannot confirm are inert. Endor Score Factors side panel for a skill in the Caution band, showing a 5 out of 10 overall score and per-dimension scores ## What is not evaluated The Endor Score is source-only. The evaluator never runs an MCP server or executes a skill to probe it. MCP scoring uses deterministic static checks. Skill scoring uses a large language model workflow, so it is not strictly deterministic. * MCP servers are evaluated from configuration and published source. Live runtime probes are disabled in the Coding Agent Governance context. * Skills are evaluated from `SKILL.md` content captured at session start. They are not exercised. * Tool name collisions between MCP servers active in the same session, and periodic re-evaluation of MCP configuration drift, are not yet flagged. ## Where you see the score You can see the score in the following locations: * **[Skills inventory](/agent-governance/inventory#skills)**: The **Endor Score** column shows the score. Select a row, then select **Endor Score Factors** under **Risk** to open the per-dimension breakdown in a side panel. * **[MCP Servers inventory](/agent-governance/inventory#mcp-servers)**: Select a server, then select **Endor Score Factors** under **Risk** to open the score and per-dimension findings in a side panel. * **[Overview](/agent-governance/overview)**: The **Skills** pie chart groups loaded skills by band across the selected time range. ## Next steps Continue with the following pages: * See [Write a policy](/agent-governance/policies) to block or alert on items above a risk threshold. * See [Review your agent inventory](/agent-governance/inventory) for the tables where the score appears. # How Coding Agent Governance works Source: https://docs.endorlabs.com/agent-governance/how-it-works/index Understand how hook events from your AI coding agents flow into the Endor Labs inventory, policies, and overview. Coding Agent Governance gives security and engineering teams visibility and control over how AI coding agents work inside your organization. Endor Labs collects events from agents, builds an inventory of your developers' AI use, and applies your policies to risky activity in real time. Use Coding Agent Governance to answer questions such as: * Which AI coding agents and MCP servers are running on developer machines? * Are agents reading sensitive files, executing dangerous commands, or talking to unapproved MCP servers? * When a policy fires, what was the developer trying to do, and which agent was responsible? Coding Agent Governance has the following components: * Hooks that run on developer machines and capture events * Coding Agent Governance policies that govern these events * Dashboards that show what your agents are doing Together, these components let you control and view the activities of AI agents across your organization. ## What Coding Agent Governance is (and isn't) Coding Agent Governance puts guardrails around what coding agents do so it can catch accidental or unintended actions before they cause damage. It reduces the chance an agent does something it shouldn't while working through a task. It is not a sandbox, firewall, or hardened security boundary. Policy controls lower risk and blast radius, but they do not guarantee that a risky action is impossible. Hard guarantees require isolation at the operating system, system call, or sandbox level. Coding Agent Governance works alongside that kind of isolation. It does not replace it. Coding Agent Governance targets accidental agent behavior. It is not designed to stop a determined user who deliberately tries to defeat the controls. ## Lifecycle of an event When a developer starts a session, an Endor Labs hook runs alongside the agent and emits a normalized event for every meaningful action. Each event carries the agent type, the user, the workspace context, and the tool, command, or file the agent acted on. The event takes two paths in parallel: * Local evaluation: The hook checks the event against a cached copy of Coding Agent Governance policies. If a policy matches, the hook can stop the action, alert the user, or pause for the developer to approve before the agent proceeds. * Centralized aggregation: The hook forwards the event to Endor Labs, where it updates the inventory, the Coding Agent Governance overview, and the policy violation log. Together, these methods enforce policies on developer machines in real time and give your security team a single place to monitor activity and plan their response. As your AI agent inventory evolves, your security team can refine policies and roll out changes. The following diagram shows the data flow in Coding Agent Governance. ## Hooks and what they govern A hook is a small script Endor Labs deploys to your developers' machines. It runs whenever the agent starts a session, submits a user prompt, calls an MCP tool, runs a shell command, or reads, writes, or deletes a file. For each event, the hook can apply a policy locally before the agent acts. Hooks enforce guardrails such as blocking dangerous commands or gating MCP tool use. They are instruction-based controls that the agent and host honor, not a tamper-proof runtime. You can write policies for the following activities: * Shell commands the agent tries to run, matched by regex. * File reads, writes, deletes, and edits, matched by regex on the file path. * MCP server and tool calls, matched by regex on server name and tool name. * Package installs, checked against the Endor Labs malware feed. * File content the agent writes or reads, scanned for secrets. The malware and secrets checks carry no authored patterns. Their verdict comes from Endor Labs data. See [Secure coding checks](/agent-governance/secure-coding). When a policy matches, the hook applies the action you chose: * **Block** stops the action and returns a deny response. The response tells the agent the action was denied by a governance policy and not to work around the block. * **Alert** logs the event without stopping the agent. * **Ask Permission** pauses for the developer to approve or deny. See [Write a policy](/agent-governance/policies) for allowlists, blocklists, and how to override in-built system policies. ## Example: a blocked malicious package install The following session shows the lifecycle end to end. A developer asks a coding agent to install an npm package, the hook checks the install against a malware policy on the developer's machine, and the block stops the install before any package code runs. ``` > Run this command in non-interactive mode: npm install plugin-proposal-json-strings I'll check what this package actually is before installing. The name looks like an unscoped variant of @babel/plugin-proposal-json-strings. Bash(npm view plugin-proposal-json-strings --json) The only remaining version is 0.0.1-security, described as a "security holding package" from npm/security-holder. The purged version history (99.10.9, 9.9.9, 8.0.11) is a dependency-confusion pattern. Bash(npm install plugin-proposal-json-strings) Error: [ENDOR LABS SECURITY POLICY BLOCK] This action was identified as an install of a known-malicious or untrusted software package. malware detected in npm package "plugin-proposal-json-strings" (flagged by MALWARE_SOURCE_OSV). Endor Labs flagged this package as known-malicious. Do not install the flagged package. If the dependency is genuinely needed, choose a non-flagged, safe version or a different well-known package, or ask the user. Do not try to install the same package by another route (a different registry, a direct download, renaming, or --force) or by disabling this check — that is treated as an evasion. Tell the user this was blocked by the Endor Labs policy "Malware: block installs of known-malicious packages". The install was blocked, and I'm not going to attempt it another way. npm install plugin-proposal-json-strings was blocked by the Endor Labs policy "Malware: block installs of known-malicious packages". The package was flagged as known-malicious (MALWARE_SOURCE_OSV). The package you probably want is the scoped Babel one, @babel/plugin-proposal-json-strings. ``` The example shows four things about how enforcement behaves: * The hook evaluated the install at the moment the agent ran it, so no package code executed. Nothing depended on the agent choosing to check the package first. * The verdict came from the Endor Labs malware feed rather than a pattern someone authored. See [Malware check](/agent-governance/secure-coding#malware-check). * The deny response tells the agent what category of action was denied, gives the evidence and the feed source, names the policy that fired, and instructs the agent not to route around the block or disable the check. The agent stopped and reported the block instead of retrying with a different registry or `--force`. * The event reached **Policy Violations** with the package, ecosystem, and feed source alongside the agent and user, so your security team sees the attempt even though nothing was installed. ## Data sent to Endor Labs Each hook event carries the metadata Endor Labs needs for inventory and policy evaluation: * Agent name, version, and (where available) model * Session and sub-session IDs * Device (endpoint) identifier * Session configuration, such as permission mode and sandbox state * User identifier when the agent provides one * Repository name (not populated for Claude Code sessions) and working directory * MCP server name, tool name, and call counts * Shell command line (regex-matched against your policies) * File path and operation type (read, write, delete, edit) * Secrets check match (rule, line, column, and fingerprint, never the secret value) * Policy match outcome and the action applied ### Secret redaction Endor Labs runs every command line, file path, URL, environment value, and MCP tool input or output through a regex-based redactor before it leaves the developer's machine. Environment variables and keys named like a secret (such as `TOKEN`, `SECRET`, `API_KEY`, `PASSWORD`, or `AUTHORIZATION`) become `[REDACTED]`. The redactor also matches common secret formats in place: URL and database-connection credentials, AWS access keys, JWTs, PEM private keys, and provider tokens such as GitHub (`ghp_*`), OpenAI, and Anthropic keys. Redaction of event payloads is best-effort regex pattern matching. A secret that does not match a known pattern or key name can still reach the backend. The [secrets check](/agent-governance/secure-coding) is separate from redaction: it detects secrets in file content on the developer's machine, and its violations carry the rule and location, never the value. On Cursor, the `sessionStart` hook returns the Endor Labs credential values to Cursor in plaintext under an `AGENT_HOOK_ENDOR_*` prefix, so subsequent hooks in the session inherit them. The values never leave the developer's machine, but anything that captures Cursor hook stdout (such as debug logging or screen recording) can see them. The hook writes two Coding Agent Governance files to a developer's disk. The hook refreshes the local policy cache (`~/.endorctl/aigovernance/endor-policies.jsonl`) at session start. When the event cache is enabled, as the recommended Cursor and Claude Code configurations do, the hook also queues events in `~/.endorctl/aigovernance/localdb/cache-.db` and flushes them in batches within about 30 seconds of hook activity, and fully at session start and end. ## What you see in Endor Labs After you deploy hooks and at least one policy exists, select **Agent Governance** from the left sidebar: Policies live with the rest of your platform policies. To open them, select **User menu** > **Policies & Rules** from the left sidebar, then select **Agent Governance**. ## Limitations of Coding Agent Governance Coding Agent Governance currently has the following limitations. ### Platform and agent coverage Coverage has the following boundaries: * Hooks run on macOS, Linux, and Windows developer machines. CI runners are not supported. See [Supported agents and platforms](/agent-governance#supported-agents-and-platforms) for the full matrix. * Policy enforcement covers Cursor, Claude Code, Codex, and GitHub Copilot. Other AI tools (such as Continue, Cody, Gemini CLI, and Amazon Q) are still discovered at session start. They appear in the **Workstation Inventory** table with a **Discovered • Not governed** status, and no hook fires for them. ### Enforcement behavior Keep the following enforcement behaviors in mind: * Policy edits take effect at the next session start on a developer's machine, when the hook refreshes the local policy cache. Tell developers to restart the agent to pick up policy changes. * Enforcement hooks fail open. If the hook cannot run, or a malware policy cannot reach the Endor Labs API for a verdict, the action proceeds. An unreadable local policy cache does not disable enforcement, because the hook falls back to the built-in system policies. When the hook cannot run, the agent and the IDE keep working, but the event is missing from inventory and policy violations until the cause is fixed. * In Cursor, **Ask Permission** pauses for approval on shell commands and MCP tool calls. It does not pause on file reads, where an **Ask** policy proceeds and is recorded, the same way **Alert** behaves. * In Codex, **Ask Permission** cannot pause a tool call, so it fails closed and denies the call with the ask message. At Codex's own approval prompts, an **Ask** policy defers to that prompt instead. See [Deploy hooks for Codex](/agent-governance/codex). * In GitHub Copilot, **Ask Permission** prompts in VS Code agent mode only. The Copilot CLI honors deny but not ask, so an **Ask** policy on a CLI session proceeds and lands under **Policy Violations**, the same way **Alert** behaves. See [Deploy hooks for GitHub Copilot](/agent-governance/copilot). * Policies match commands and patterns, not the end effect. An agent can occasionally reach the same result another way. That trade-off comes with best-effort, pattern-based controls. ### Attribution and visibility Attribution has the following gaps: * User attribution is populated when the agent's hook payload includes a user identifier. Cursor supplies one on most events. Claude Code, Codex, and GitHub Copilot attempt to derive one from the local environment and may succeed depending on the version and configuration, but the value can still be empty. The **User** column on **Policy Violations** and the user count on the **Overview** stay empty for events without an identifier. * endorctl captures device (endpoint) attribution on every event, but Coding Agent Governance does not surface it in the user interface. You cannot filter or scope inventory or policy violations by device. * Claude Code sub-agent activity may carry no user identity, and the hook does not record sub-agent MCP tool calls that a policy cleanly allows. Policies still evaluate and enforce on sub-agent activity. ### Inventory and scoring Inventory and scoring have the following limits: * Endor Labs computes MCP server risk scores only for servers it finds in an agent's configuration files. A server invoked without a discoverable configuration entry can appear in inventory from its tool calls without a score. * Endor Labs discovers MCP servers that enabled Claude Code plugins contribute, from the installed-plugin registry (`~/.claude/plugins`) and from skills-directory plugins. Each server appears in inventory under the name Endor Labs derives from its runtime (the command binary or URL host), falling back to `/` when it cannot derive one, attributed to the level that installed the plugin. Endor Labs does not inventory disabled plugins or marketplace plugins that are not installed locally. * Endor Labs does not assess agent plugins as a single unit. It evaluates the MCP servers and skills a plugin contributes, not the plugin itself. * File access matching is regex-based on path. The [secrets check](/agent-governance/secure-coding#secrets-check) adds content-aware secret detection, but Endor Labs does not redact or rewrite the content an agent reads. * Skills inventory reflects skills discovered in the workspace and user-home directories at session start. Skills loaded at runtime by the agent, or installed outside those directories, might not appear. See [Skills](/agent-governance/inventory#skills) for the exact paths scanned. * Hooks capture session configuration such as permission mode and sandbox state. Use [Session Posture](/agent-governance/policies#session-posture) policies to match sessions by sandbox setting. Richer client-posture context in the inventory is limited today. # Coding Agent Governance Source: https://docs.endorlabs.com/agent-governance/index Secure your code generation factory. Coding Agent Governance gives security and engineering teams visibility and control over AI coding agents across developer workstations and cloud environments. It inventories the agents, models, MCP servers, and skills in use. It monitors agent actions such as commands, file access, and tool calls, and enforces policies to block, alert on, or require approval for risky behavior before it executes. Secure coding checks extend these controls with detection backed by Endor Labs intelligence. The malware check looks up packages in the Endor Labs malware feed, and the secrets check scans content the agent writes or reads. See [Secure coding checks](/agent-governance/secure-coding) for more information. These controls are guardrails for accidental agent behavior, not a sandbox or hard security boundary. See [How Coding Agent Governance works](/agent-governance/how-it-works) for what that means in practice and how events flow into Endor Labs. Keep three operating caveats in mind when you rely on Coding Agent Governance: * **Enforcement fails open.** If a hook cannot run, or a malware policy cannot reach Endor Labs for a verdict, the action proceeds, and the event is missing from inventory and policy violations until the cause is fixed. An unreadable policy cache still enforces the built-in system policies. See [Limitations](/agent-governance/how-it-works#limitations-of-coding-agent-governance). * **Policy changes apply at the next session start.** Hooks evaluate against the policy snapshot fetched when a session starts, so tell developers to restart the agent after a policy edit. See [Local policy cache](/agent-governance/policies#local-policy-cache). * **Redaction is pattern-based.** The redactor masks secret-named keys and known credential formats before an event leaves the machine, but a secret in an unknown format can still reach the backend. See [Data sent to Endor Labs](/agent-governance/how-it-works#data-sent-to-endor-labs). ## Supported agents and platforms Coding Agent Governance enforces policies for supported agents on developer machines. Endor Labs discovers other AI coding tools at session start but does not govern them. ¹ **Claude Cowork**: Not supported while [claude-code issue #40495](https://github.com/anthropics/claude-code/issues/40495) is open. The Cowork sandbox ignores user settings, managed settings, and environment variables, so governance hooks never load and Cowork sessions are neither monitored nor governed. The failure is silent. Use Claude Code (app or CLI) for governed work. ² **Claude Cloud**: Hooks run inside the hosted sandbox and fire from session start. ³ **Cursor Cloud**: Agent lifecycle events, such as stop and agent response, do not fire. ⁴ **Cursor CLI**: Shell command hooks fire reliably. Prompt, file edit, and stop events do not. On Windows, run the CLI under WSL. ## Set up Confirm tenant access, check license eligibility, and create an API key with the **AI Audit User** role. See [Prerequisites](/agent-governance/prerequisites). Install hooks for [Cursor](/agent-governance/cursor), [Claude Code](/agent-governance/claude-code), [Codex](/agent-governance/codex), and [GitHub Copilot](/agent-governance/copilot). To roll them out across a fleet, see [MDM deployment](/agent-governance/mdm-deployment) and build each configuration with the [in-browser generator](/agent-governance/mdm-deployment#generate-a-configuration-in-your-browser). ## Operate Find the agents, MCP servers, models, and skills your developers use, each rated with an [Endor Score](/agent-governance/endor-score). See [Review your agent inventory](/agent-governance/inventory). Filter, read, and respond to violations from your governed agents as they arrive. See [Triage policy violations](/agent-governance/policy-violations). Endor Labs ships an in-built policy catalog enabled by default. Review it, then add custom rules for what to block, alert on, or ask permission for. See [Write a policy](/agent-governance/policies). ## Plan your rollout Pick your AI coding agent and rollout style. The wizard returns a tailored checklist with deep links to every page you need. ## Names you'll see Each name is tied to a specific surface of the same capability: * **Coding Agent Governance** is the feature name, used across this documentation. * **Agent Governance** is the name in the Endor Labs user interface, on the left-sidebar entry and on the policy tab under **Policies & Rules**. * **AI Audit** is the machinery hooks run as. It appears in the **AI Audit User** role for hook API keys, the [endorctl ai-audit](/developers-api/cli/commands/ai-audit) command, and the `ENDOR_AI_AUDIT_*` environment variables. ## Frequently asked questions No. It puts guardrails around agent behavior, not a sandbox, firewall, or hardened boundary. Policy controls lower the risk and blast radius of agent mistakes, but hard guarantees require isolation at the operating system, system call, or sandbox level, which Coding Agent Governance works alongside. See [What Coding Agent Governance is (and isn't)](/agent-governance/how-it-works#what-coding-agent-governance-is-and-isnt). No, and that is by design. It targets accidental agent behavior, not a person deliberately trying to defeat the controls. See [What Coding Agent Governance is (and isn't)](/agent-governance/how-it-works#what-coding-agent-governance-is-and-isnt). The agent receives a deny response explaining that a governance policy blocked the action and telling it not to work around the block. The event appears in **Policy Violations**. See [Hooks and what they govern](/agent-governance/how-it-works#hooks-and-what-they-govern). Policies match commands and patterns, not the end effect, so an agent can occasionally reach the same result another way. That trade-off comes with best-effort, pattern-based controls. See [Limitations](/agent-governance/how-it-works#limitations-of-coding-agent-governance). **Block**, **Alert** (record only), or **Ask Permission**, written as blocklists or allowlists over shell commands, file access, and MCP tool calls, plus secure coding checks for malware and secrets. See [Write a policy](/agent-governance/policies). Yes. The malware check stops installs of packages flagged by the Endor Labs malware feed, and the secrets check scans content the agent writes or reads on the developer's machine. A secrets violation reports the rule and location, never the secret value. See [Secure coding checks](/agent-governance/secure-coding). Yes. Override a system policy with one of the same name and a different action, turn it off in the policy list, or author your own from the same templates. See [Write a policy](/agent-governance/policies). Every command line, file path, URL, environment value, and MCP tool input or output passes through a redactor on the developer's machine before the hook sends anything. Secret-named keys and common credential formats become `[REDACTED]`. Prompt text stays local. See [Data sent to Endor Labs](/agent-governance/how-it-works#data-sent-to-endor-labs). Endor Labs discovers skills at session start and rates them with an [Endor Score](/agent-governance/endor-score), and policies can flag or block suspicious ones. It assesses plugins through the MCP servers and skills they contribute, not as a single unit. See [Skills](/agent-governance/inventory#skills). # Review your agent inventory Source: https://docs.endorlabs.com/agent-governance/inventory/index Find the AI coding agents, MCP servers, models, and skills your developers use, with last-seen activity for each. The Coding Agent Governance inventory is a live picture of what your developers run on a workstation. Each entry aggregates events from the deployed hooks so you can answer the question, "What AI is in my organization right now?" ## Open the inventory Select **Agent Governance** from the left sidebar, then choose what you want to review: * **Workstation Inventory** to see installed agents and their activity. * **MCP Servers** to see the MCP servers your agents call. * **AI Models** to see the underlying models invoked through agents. * **Skills** to see the skills your agents loaded during sessions. Each entry lets you filter, search, and pivot into the Coding Agent Governance overview, policies, or policy violations. ## Workstation Inventory Selecting **Workstation Inventory** shows every agent and AI tool your hooks have observed. Above the table, three summaries provide context: a **Coding Agents** pie that breaks down active agents, a **Sessions This Week** trend, and a **Developers with AI** counter. Workstation Inventory Branded logos appear only for governed agents such as Cursor, Claude Code, Codex, and GitHub Copilot. Every other row (including discovered tools and any agent type the user interface has not yet learned to recognize) shows a generic AI model icon. Use this to spot agents that are out of date, developers whose agent has stopped reporting, and tools your developers added that you have not adopted. Select a row to open the agent's detail drawer. The header shows a **Governed** or **Discovered** status chip, followed by **Sessions**, **Distinct Users**, and **Last Seen** cards, the reported version, and an **Activity** section. Under **Activity**, select **Recent Events** to open the event list in a side panel, or **Policy Violations** to jump to the violations for that agent. Workstation Inventory with the Cursor agent detail drawer open, showing the Governed status chip, usage cards, version, and Activity section ## MCP Servers Selecting **MCP Servers** shows every MCP server your agents have called. Three charts summarize them above the table: **Local vs. Remote** by where the server runs, **Approved & Blocked** by your review decision, and **Suspicious & Malicious** by threat classification. Use the **Risk** filter to focus on the riskiest servers. Policies set the review and threat labels. A policy with an inventory classification tags the servers it matches as **Approved**, **Blocked**, **Suspicious**, or **Malicious**, and servers with no matching policy show **Unreviewed**. See [Inventory classification](/agent-governance/policies#inventory-classification) to set the tags. The label and the score are different signals. The label records your organization's decision, applied by your policies. The [Endor Score](/agent-governance/endor-score) and the risk band derived from it are computed by Endor Labs from the server's configuration and source. A low-scoring server stays **Unreviewed** until a policy classifies it. To connect the two, write an [MCP Server Posture](/agent-governance/policies#mcp-server-posture) policy that matches on a score threshold and carries an inventory classification. For example, tag every server scoring 4 or lower as **Blocked**. MCP Servers inventory Use this to identify unsanctioned MCP servers. Select a server to open its detail drawer: **Tool Calls**, **Distinct Users**, and **Last Seen** cards, a details section with the server type, host, transport, launch command, available tools, and environment variable names, and a **Risk** section. Under **Risk**, the **Policy Violations** count links to the violations for that server, and **Endor Score Factors** opens the per-dimension [Endor Score](/agent-governance/endor-score) breakdown in a side panel. See [Write a policy](/agent-governance/policies) to gate access to specific servers. MCP server detail drawer showing usage cards, the server details section, and the Risk section with the Endor Score Factors entry Endor Labs doesn't score agent plugins as a single unit. It evaluates the MCP servers and skills a plugin contributes. See [How Coding Agent Governance works](/agent-governance/how-it-works#inventory-and-scoring) for related inventory limits. ## AI Models Selecting **AI Models** shows the language models invoked through your agents. Above the table, an **AI Models by Provider** pie breaks down model use by provider, and a **Top Model Sessions** list ranks the most-used models in the selected time range. Every column in the table is sortable. AI Models inventory Use this to track model adoption and to flag models that fall outside your approved set. ## Skills Selecting **Skills** shows the skills your agents loaded during sessions. Three charts summarize them above the table: **Approved & Blocked** by your review decision, **Suspicious & Malicious** by threat classification, and **Top 5 Riskiest Skills** by Endor Score. Use the **Risk** filter to focus on the riskiest skills. As with MCP servers, policies set the review and threat labels. See [Inventory classification](/agent-governance/policies#inventory-classification). These labels are separate from the score bands (**Unauthorized**, **Caution**, **Safe**) that come from the [Endor Score](/agent-governance/endor-score). Skills inventory Use this to triage low-scoring skills and to coordinate with developers on which skills your organization trusts. Policies can flag or block skills by name or by Endor Score. See [Skill Access](/agent-governance/policies#skill-access) to write those rules. Select a row to open the skill's detail drawer: usage cards, the frontmatter metadata (description, allowed tools, license, compatibility, file count, and file path), a **Content** section that opens the captured `SKILL.md` in a side panel, and a **Risk** section where **Endor Score Factors** opens the per-dimension score breakdown. Skill detail drawer showing usage cards, frontmatter metadata, the SKILL.md content entry, and the Risk section ### How skills are discovered At every session start, the hook scans for `SKILL.md` files in two directory scopes and reports every skill it finds on the session-start event. Cursor scans across the common agent skill directories so that a skill installed for any supported agent appears in the inventory. ### `SKILL.md` format Each skill is a directory that contains a `SKILL.md` file with YAML frontmatter. ```yaml theme={null} --- name: my-skill description: One-line summary of what the skill does. license: Apache-2.0 compatibility: Requires Python 3.14+ allowed-tools: - Bash - Read --- # Skill body in Markdown ``` The frontmatter exposes these keys to the Endor Labs inventory: * `name`: Used as the skill identifier. If it's missing, the inventory uses the parent directory name instead. * `description`: Shown on the skill row and detail page. * `license`: Surfaced alongside the skill for compliance review. * `compatibility`: Free-text dependency requirement. * `allowed-tools`: List of tools the skill may call. Accepts a YAML list or a space-separated string. ### Discovery limits and behavior Skill discovery works within the following limits: * A single event carries up to 100 skills. The hook skips any additional skills. * The hook truncates each skill's content to 128 KiB and caps a single event payload at 10 MiB. When a skill's content would push the payload past the cap, the hook reports that skill with metadata only. * The hook skips directories named `.git`, `node_modules`, `vendor`, `__pycache__`, and `.venv` to keep discovery fast. * The hook doesn't follow symbolic links. * If two skills share the same `name`, the first one encountered wins. Workspace directories scan before user-home directories. * The hook skips `SKILL.md` files it cannot read, so a single corrupt skill doesn't break inventory. A readable file with malformed frontmatter still appears, using the directory name as the skill name. The hook doesn't capture skills the agent loads at runtime from outside the scanned directories. ## Next steps Continue with the following pages: * See [Write a policy](/agent-governance/policies) to act on what the inventory shows. * See [Read the Coding Agent Governance overview](/agent-governance/overview) to track inventory trends across a time range. # Deploy Coding Agent Governance with MDM Source: https://docs.endorlabs.com/agent-governance/mdm-deployment/index Generate Cursor hooks, Claude Code settings, Codex requirements, or a macOS configuration profile for managed developer machines. Coding Agent Governance configurations connect Cursor, Claude Code, and Codex events to Endor Labs. Use this page to generate hook configuration for individual machines or managed fleets. You can create Cursor `hooks.json`, Claude Code `settings.json`, Codex `requirements.toml`, or a macOS configuration profile for Claude Code or Codex. The generated hooks install and update endorctl when a coding agent session starts. ## Before you begin Complete the following tasks before you generate a configuration: * Complete the [Coding Agent Governance prerequisites](/agent-governance/prerequisites). * Create an API key with the **AI Audit User** role. * Identify the namespace that owns your Coding Agent Governance policies. * For manual generation, install `git` on the admin machine. The scripts run with system tools only. Creating a macOS configuration profile also requires macOS and `plutil`. ## Generate a configuration in your browser The browser generator assembles the configuration locally. Your API key, secret, namespace, and environment variable values are never sent to Endor Labs or GitHub. Use the manual generation steps below if the browser generator isn't available or can't fetch its source files. ## Generate a configuration manually The [Endor Labs MDM scripts repository](https://github.com/endorlabs/mdm-scripts/tree/main/agent-governance) is the authoritative source for the generator scripts. Clone the repository on an admin machine. ```bash theme={null} git clone https://github.com/endorlabs/mdm-scripts cd mdm-scripts/agent-governance ``` Set your credentials as environment variables. The generator reads these exact variable names, and prompts for any missing credential when you run it interactively. ```bash theme={null} export ENDOR_API_CREDENTIALS_KEY="" export ENDOR_API_CREDENTIALS_SECRET="" export ENDOR_NAMESPACE="" ``` Generate the configuration that matches your coding agent and deployment method. Generate `hooks.json` for macOS or Linux. ```bash theme={null} scripts/render.sh --agent cursor \ --api-key "$ENDOR_API_CREDENTIALS_KEY" \ --api-secret "$ENDOR_API_CREDENTIALS_SECRET" \ --namespace "$ENDOR_NAMESPACE" \ -o cursor-hooks.json ``` For Windows, add `--target-os windows`. The generated hook uses an encoded PowerShell command that can run from Git Bash, PowerShell, or Command Prompt. ```bash theme={null} scripts/render.sh --agent cursor --target-os windows \ --api-key "$ENDOR_API_CREDENTIALS_KEY" \ --api-secret "$ENDOR_API_CREDENTIALS_SECRET" \ --namespace "$ENDOR_NAMESPACE" \ -o cursor-hooks.json ``` Generate `settings.json` for a user installation, Linux managed settings, or Windows deployment. ```bash theme={null} scripts/render.sh --agent claude \ --api-key "$ENDOR_API_CREDENTIALS_KEY" \ --api-secret "$ENDOR_API_CREDENTIALS_SECRET" \ --namespace "$ENDOR_NAMESPACE" \ -o claude-settings.json ``` For Windows, add `--target-os windows`. ```bash theme={null} scripts/render.sh --agent claude --target-os windows \ --api-key "$ENDOR_API_CREDENTIALS_KEY" \ --api-secret "$ENDOR_API_CREDENTIALS_SECRET" \ --namespace "$ENDOR_NAMESPACE" \ -o claude-settings.json ``` Pipe the Claude Code settings through `render-plist.sh` to create a `.mobileconfig` file. Replace the identifier and organization with values for your organization. ```bash theme={null} scripts/render.sh --agent claude \ --api-key "$ENDOR_API_CREDENTIALS_KEY" \ --api-secret "$ENDOR_API_CREDENTIALS_SECRET" \ --namespace "$ENDOR_NAMESPACE" \ -o - \ | scripts/render-plist.sh \ --identifier com.example.ai-governance.claudecode \ --organization "Example Organization" \ --name "Claude Code - Endor AI Governance" \ -o com.anthropic.claudecode.mobileconfig ``` Generate `requirements.toml` with managed hooks for macOS or Linux. Hooks from a managed requirements source are trusted by policy and run without per-user approval. Codex has no managed environment block, so the credentials are baked into every hook command. Treat the file as a secret. ```bash theme={null} scripts/render.sh --agent codex \ --api-key "$ENDOR_API_CREDENTIALS_KEY" \ --api-secret "$ENDOR_API_CREDENTIALS_SECRET" \ --namespace "$ENDOR_NAMESPACE" \ -o codex-requirements.toml ``` For Windows, add `--target-os windows`. Pipe the Codex requirements through `render-plist.sh --style mcx` to create a `.mobileconfig` file that delivers the TOML as a managed preference. Replace the identifier and organization with values for your organization. ```bash theme={null} scripts/render.sh --agent codex \ --api-key "$ENDOR_API_CREDENTIALS_KEY" \ --api-secret "$ENDOR_API_CREDENTIALS_SECRET" \ --namespace "$ENDOR_NAMESPACE" \ -o - \ | scripts/render-plist.sh --style mcx \ --identifier com.example.ai-governance.codex \ --organization "Example Organization" \ --name "Codex - Endor AI Governance" \ -o com.openai.codex.mobileconfig ``` The generated configuration contains your API key and secret. Treat the output and its MDM policy as secrets. Restrict access and rotate the API key if someone exposes the configuration. ### Configure optional behavior The generator enables the local response cache by default. Add `--env ENDOR_AI_AUDIT_NO_BLOCKING=true` to evaluate and record actions without blocking them. ```bash theme={null} scripts/render.sh --agent cursor \ --api-key "$ENDOR_API_CREDENTIALS_KEY" \ --api-secret "$ENDOR_API_CREDENTIALS_SECRET" \ --namespace "$ENDOR_NAMESPACE" \ --env ENDOR_AI_AUDIT_NO_BLOCKING=true \ -o cursor-hooks.json ``` Add `--skip-endorctl-update` if your fleet provisions endorctl separately and shouldn't check for updates when a session starts. ## Deploy the generated configuration Deliver the generated file through your mobile device management (MDM) or configuration management tool. ### Deploy Cursor hooks Deliver `cursor-hooks.json` to the location that matches your deployment: * For a local trial, copy `cursor-hooks.json` to `~/.cursor/hooks.json`. * On managed macOS machines, deliver it to `/Library/Application Support/Cursor/hooks.json`. * On managed Linux machines, deliver it to `/etc/cursor/hooks.json`. * On Windows, push `cursor-hooks.json` with your MDM tool. See [Deploy hooks for Cursor](/agent-governance/cursor) to verify the installation and review the registered hook events. ### Deploy Claude Code settings Deliver the generated Claude Code configuration to the location that matches your deployment: * For a local trial, copy `claude-settings.json` to `~/.claude/settings.json`. * On managed Linux machines, deliver it to `/etc/claude-code/managed-settings.json`. * On Windows, push `claude-settings.json` with your MDM tool. * On managed macOS machines, upload `com.anthropic.claudecode.mobileconfig` as a custom profile. See [Deploy hooks for Claude Code](/agent-governance/claude-code) to verify the installation and review the registered hook events. ### Deploy Codex requirements Deliver the generated Codex configuration to the location that matches your deployment: * On managed macOS and Linux machines, deliver `codex-requirements.toml` to `/etc/codex/requirements.toml`. * On managed macOS machines, you can instead upload `com.openai.codex.mobileconfig` as a custom profile. * On Windows, push `codex-requirements.toml` to `%ProgramData%\OpenAI\Codex\requirements.toml` with your MDM tool. See [Deploy hooks for Codex](/agent-governance/codex) to verify the installation and review the registered hook events. ## Update a deployment The session hook installs endorctl on first use and checks for updates during later session starts. It verifies the downloaded binary with SHA-256. Regenerate and redeploy the configuration when you change credentials, environment variables, or delivery settings. Server-side Coding Agent Governance policy changes don't require a new configuration. ## Keep a fleet current with the scheduled runner The [mdm-scripts repository](https://github.com/endorlabs/mdm-scripts/tree/main/agent-governance) also ships `scripts/runner.sh`, which replaces one-shot generation with a self-updating deployment on macOS and Linux. Paste it into your MDM as a recurring script body (a Jamf script, Kandji Custom Script, or JumpCloud Command) and edit the settings block at the top to pick the agent and pin a reviewed revision. On each run it fetches the repository at that revision, renders the configuration on the endpoint, and replaces the installed file atomically, only when the result changed. Repository, credential, and flag changes then roll out on the next scheduled run without a redeploy. Keep the following in mind: * The MDM must set `ENDOR_API_CREDENTIALS_KEY`, `ENDOR_API_CREDENTIALS_SECRET`, and `ENDOR_NAMESPACE` in the script's environment. Use an API key with the **AI Audit User** role. * Endpoints need only `curl` and `tar`, which ship with macOS and Linux. * Windows does not use the runner. Pre-generate the configuration and push it with Intune or your MDM tool. # Coding Agent Governance overview Source: https://docs.endorlabs.com/agent-governance/overview/index See developer adoption, model use, and policy enforcement trends across your entire fleet on one page. The Coding Agent Governance overview pulls counts and trends from every event your hooks have captured. Use it to answer the question, "How is Coding Agent Governance going across my organization right now?" ## Open the overview Select **Agent Governance** from the left sidebar. The overview opens by default. Use **Time Range** at the top to scope every metric and chart to a window, such as the last hour, day, week, or a custom range. Coding Agent Governance overview ## Top metrics Five counts summarize fleet-wide activity. Hover any metric to see its definition. ## Composition charts Three pie charts show what your fleet is using during the selected time range. * **Top Models**: The top three models by session count. * **Top MCP Servers**: The top three MCP servers by tool-call count. * **Skills**: Loaded skills bucketed as **Unauthorized**, **Suspicious**, **Approved**, or **Unscored** by their [Endor Score](/agent-governance/endor-score). Use these to spot a model, an MCP server, or a skill gaining ground that you have not approved. ## Top violation widgets Below the pies, three card tables surface the busiest policy violations in the selected time range. Each card shows a few rows and links to **Policy Violations** with the matching filter applied. * **Most Triggered Policy Violations**: Top policies by violation count, across every category. * **File Access Blocked**: Top **File Access** matches that the hook stopped. * **Dangerous Commands Blocked**: Top **Dangerous Command** matches that the hook stopped. ## When the overview is empty The overview shows **No data available** when nothing matches the current time range. Confirm: * **Time Range** is wide enough to include relevant events. * Hooks are deployed and reporting. See [Review your agent inventory](/agent-governance/inventory) to confirm activity is arriving. ## Next steps Continue with the following pages: * See [Triage policy violations](/agent-governance/policy-violations) to drill into the events behind the counts. * See [Review your agent inventory](/agent-governance/inventory) to dig into the agents, MCP servers, models, and skills behind the charts. # Coding Agent Governance policies Source: https://docs.endorlabs.com/agent-governance/policies/index Block dangerous commands, restrict file access, and gate MCP server use with allow and deny patterns for AI coding agents. Coding Agent Governance policies tell hooks how to react to risky agent activity in real time. Each policy combines a template, a set of patterns, and an action. When a matching event arrives, the hook applies the action before the agent runs the operation. Endor Labs ships nearly 50 system policies. Almost all ship enabled by default, so enforcement starts as soon as you deploy hooks. They block destructive commands, secret and credential access, risky git and publish operations, known-malicious MCP servers, and attempts to bypass the Package Firewall. They also ask before riskier-but-routine actions, such as installing packages or force-pushing a branch. See [Out-of-the-box policies](#out-of-the-box-policies) for the complete list. You can change any system policy for your namespace. You can override it with a policy of the same name and a different action, turn it off in the policy list, or author your own from the same templates. See [Policy propagation across namespaces](#policy-propagation-across-namespaces). The following templates are available: * [**File Access**](#file-access): control reads, writes, edits, and deletes in the workspace. * [**Command Execution**](#command-execution): control the shell commands an agent runs. * [**MCP Server Access**](#mcp-server-access): control which MCP servers and tools an agent calls. * [**MCP Server Posture**](#mcp-server-posture): match MCP servers by name or by Endor Labs score. * [**Skill Access**](#skill-access): control which skills run, by name or by Endor Labs score. * [**Session Posture**](#session-posture): match sessions by user, sandbox, and models. * [**Malware**](#malware): check the packages an agent installs against the Endor Labs malware feed. * [**Secrets**](#secrets): scan content the agent writes or reads for leaked secrets. Hooks evaluate events against the policy snapshot they read from the namespace. ## Manage Coding Agent Governance policies To open Coding Agent Governance policies: 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Agent Governance**. ### View Coding Agent Governance policies On the **Agent Governance** listing, you can view policies grouped by what they govern: * **All Policies** for every policy in scope. * **Coding Agents** for command execution policies. * **File Access** for file-operation policies. * **MCP Servers** for MCP server and tool access policies. * **MCP Server Posture** for policies that match MCP servers by Endor Labs score. * **Sessions** for session posture policies. * **Skills** for skill policies. ### Create a Coding Agent Governance policy 1. Click **Create Agent Governance Policy**. 2. Under **Define a Policy**, choose a template under **Policy Template**: * **File Access** under **Coding Agents**: Control reads, writes, deletes, and edits in the workspace. * **Command Execution** under **Coding Agents**: Control the shell commands the agent runs. * **MCP Server Access** under **MCP Servers**: Control which MCP servers and tools the agent can call. * **MCP Server Posture** under **MCP Servers**: Match MCP servers by name or by Endor Labs score. * **Skill Access** under **Skills**: Control which skills can run, by name or by Endor Labs score. * **Session Posture** under **Sessions**: Match sessions by user identity, sandbox, and models. 3. Under **List Type**, choose **Allowlist** to permit only matching items, or **Blocklist** to block matching items. 4. Fill in the pattern fields the template exposes. See [Templates and patterns](#templates-and-patterns) for field names and syntax. 5. Under **Choose an Action**, select the action your hook should take when an event matches: * **Block** stops the action and returns a deny response to the agent. * **Alert** lets the action proceed and records the event under **Policy Violations**. * **Ask Permission** pauses the agent until the developer approves or denies. 6. Optionally, under **Inventory Classification**, choose **Allow**, **Block**, **Suspicious**, or **Malicious** to tag the MCP servers or skills the policy matches. **None**, the default, applies no tag. The selector appears for the **MCP Server Posture** and **Skill Access** templates. See [Inventory classification](#inventory-classification). 7. Optionally, fill in **User Message**. The developer sees it when the policy fires, and the agent receives it inside a standard deny response that names the policy category and tells the agent not to work around the block. Endor Labs stores the **Agent Message** field on the policy but does not currently deliver it to the agent. 8. Under **Name Your Policy**, enter a **Name** that describes the policy intent. 9. Click **Create Agent Governance Policy**. The policy is now active. Local hooks pick it up at the next session start. The form groups templates by what the agent is doing, while the **Agent Governance** policy listing groups them by what they govern. **File Access** is grouped under **Coding Agents** in the form, but its policies appear under **File Access** in the listing. ## Coding Agent Governance templates and patterns Each template targets one activity type and exposes the fields that activity uses. All pattern fields use regular expressions, not globs. Anchor with `^` and `$` to match the full string, and escape literal characters such as `.` and `/`. ### File Access Use this template to govern reads, writes, deletes, and edits in the workspace. * **File Operation**: Choose **Any**, **Read**, **Write**, **Delete**, or **Edit**. * **File Name Patterns**: Regex patterns matched against file paths. Add one pattern per row with **+ Add file pattern**. * **Example blocklist patterns**: `.*\.env$`, `.*\.pem$`, `.*/secrets/.*`. ### Command Execution Use this template to govern shell commands the agent runs. * **Custom Command Patterns**: Regex patterns matched against shell commands. Add one pattern per row with **+ Add command**. * **Example blocklist patterns**: `^rm\s+-rf\s+/`, `^curl\s+.*\|\s*(sh|bash)\b`. ### MCP Server Access Use this template to govern which MCP servers and tools your agents can call. * **Server Name Patterns**: Regex patterns matched against MCP server names. Add one pattern per row with **+ Add server pattern**. * **Tool Name Patterns**: Regex patterns matched against MCP tool names. Add one pattern per row with **+ Add tool pattern**. * **Example blocklist patterns**: `.*-prod$` for any production server, or `.*delete.*` for tool names that include `delete`. ### MCP Server Posture Use this template to match MCP servers by name, by Endor Labs score, or both. It scores server-level posture rather than individual tool calls, so reach for it when you want to gate on how risky a server is. * **Server Name Patterns**: Regex patterns matched against MCP server names. * **Overall score at or below**: Match when the server's Endor Score (`1`-`10`, higher is safer) is at or below this value. Leave blank to ignore the overall score. * **Per-dimension thresholds**: Optionally match on one dimension instead of the overall score: **Supply Chain & Provenance**, **Authentication & Authorization**, **Operational Hygiene**, or **Input Validation & Injection**. When you set both a name pattern and a score threshold, a server must match the name and a threshold. See [Endor Score](/agent-governance/endor-score) to learn how Endor Labs computes MCP server scores. ### Skill Access Use this template to control which agent skills can run, by name, by Endor Labs skill score, or both. * **Skill Name Patterns**: Regex patterns matched against skill names. * **Overall score at or below**: Match when the skill's Endor Score (`1`-`10`, higher is safer) is at or below this value. Leave blank to ignore the overall score. * **Per-dimension thresholds**: Optionally match on one dimension: **Instruction Integrity**, **Data Protection**, **Permission Boundaries**, or **External Dependencies**. When you set both a name pattern and a score threshold, a skill must match the name and a threshold. See [Endor Score](/agent-governance/endor-score) to learn how Endor Labs computes skill scores. ### Session Posture Use this template to match agent sessions by posture: who runs the session, whether it is sandboxed, and which models it uses. Each group is optional, so leave a group empty to ignore it. * **User name patterns**: Regex patterns matched against the session user, such as `svc-.*` or `.*@example\.com`. * **Sandbox enabled**: Match sessions where the sandbox is enabled, disabled, or either. * **Default model patterns**: Regex patterns matched against the session's default model, such as `gpt-.*`. * **Available model patterns**: Regex patterns matched against the models offered to the session, such as `claude-.*`. #### Match on more session configuration through the REST API The policy form exposes the four criteria above. Through the REST API, a session policy can match on more of the session's configuration, read from the agent's config at any level (repository, user, or enterprise). Every group you set must match, and an empty group is ignored. Set these fields on the session activity. * `composer_mode_matchers`: Regex matched against the composer mode, such as `agent`, `ask`, or `edit`. * `source_matchers`: Regex matched against how the session started, such as `startup`, `resume`, or `clear`. * `is_background_agent`: Match sessions by whether they run as a background agent. * `sandbox.fail_if_unavailable`: Match sessions by whether they require the sandbox to be available. * `sandbox.allowed_host_matchers`: Regex matched against the sandbox's allowed network hosts, to catch overly permissive rules such as `.*`. * `permissions.default_mode_matchers`: Regex matched against the permission default mode, such as `bypassPermissions`. * `permissions.bypass_disabled`: Match sessions by whether permission bypass is disabled. * `permissions.allowed_command_matchers` and `permissions.denied_command_matchers`: Regex matched against the session's allowed and denied command lists. * `hook.event_name_matchers`: Regex matched against configured hook event names, such as `PostToolUse`. * `hook.command_matchers`: Regex matched against configured hook command strings, such as `curl .* | bash`. Manage a policy that uses these fields through the API end to end. Saving a policy from the form rebuilds its activity from the fields the form exposes, which silently drops any REST-only criteria. #### Match on developer identity When you enroll the Anthropic Compliance API integration, session policies can also match the developer's organization identity. Endor Labs syncs your Claude Enterprise directory on a schedule and resolves each Claude Code session to a directory entry by email. The hook reads the developer's email from the local git configuration (falling back to the `GIT_AUTHOR_EMAIL` and `EMAIL` environment variables), and Endor Labs matches it against the corporate email in the synced directory, so resolution depends on developers committing under their corporate email. Set these criteria through the REST API. The policy form does not expose them yet. * `role_matchers`: Regex patterns matched against the developer's organization roles. Any match counts. * `group_matchers`: Regex patterns matched against the developer's organization groups. Any match counts. * `managed_status_match`: Match sessions from a managed account (in your directory) or an unmanaged one (a Claude account outside your directory, a shadow-AI signal). Every identity criterion you set must match. When hooks can't resolve a session's identity, they skip policies that use identity criteria, so they never block an unresolved session by mistake. Identity matching applies to Claude Code sessions and to session-level events only. To enroll, create an integration with your Anthropic Compliance API access key through the REST API. The sync stores directory entries (email, display name, roles, and groups) in your Endor Labs namespace, so review that data flow with your privacy team. ### Malware Use this template to check the packages an agent installs against the Endor Labs malware feed. The policy carries no patterns to author. Matching the activity means running the check, and the block or allow verdict comes from the feed. * **Ecosystems**: Optional list that narrows the check to specific ecosystems, such as `npm` or `pypi`. An empty list checks every ecosystem. Create and edit malware policies through the REST API. See [Secure coding checks](/agent-governance/secure-coding#malware-check) for what the check inspects, the evidence a violation carries, and a full creation example. ### Secrets Use this template to scan content the agent writes or reads for secrets, using the Endor Labs secret detection rules. The policy carries no patterns to author. Matching the activity means running the scan, and the verdict comes from the detection rules. * **Include file patterns**: Optional regex list that limits scanning to matching paths. An empty list scans every file the event covers. * **Exclude file patterns**: Optional regex list that skips paths such as test fixtures or vendored directories. Exclusions apply after inclusions. Create and edit secrets policies through the REST API. See [Secure coding checks](/agent-governance/secure-coding#secrets-check) for what the scan detects and what a violation carries. ## Allowlist or blocklist Choose **Allowlist** when you want to permit a small, known set of items and block everything else. Use it for sensitive areas, such as production credentials or a curated set of approved MCP servers. Choose **Blocklist** when you want to permit most activity and block known-dangerous items. Use it for destructive commands, leaked-secret paths, and unapproved MCP servers. ## Actions Each policy applies one of three actions on a match. ## Inventory classification A policy can tag the MCP servers and skills it matches in your inventory, in addition to taking an action. Choose a value under **Inventory Classification** when you create a policy from the **MCP Server Posture** or **Skill Access** template. The tag is independent of the action, so a policy can block and tag, tag only, or act only. The tag lands on the inventory record on one of two independent axes: * Review status: **Allow** marks the item **Approved**. **Block** marks it **Blocked** (skills show **Unapproved**). * Threat level: **Suspicious** or **Malicious**. When several policies match the same item, the strongest value per axis wins: **Block** beats **Allow**, and **Malicious** beats **Suspicious**. The inventory record keeps the name of the policy that set each tag as evidence. Classification follows your current policy set, so turning a policy off lets the next event reclassify the item. Items no classification policy has matched show **Unreviewed**. These tags feed the **Approved & Blocked** and **Suspicious & Malicious** summaries on the inventory pages. See [Review your agent inventory](/agent-governance/inventory) to read them. ## Scope a policy by repository or user Through the REST API, a policy can carry a scope that limits which events it applies to. A scope holds two regex lists: * `scope.repository_matchers`: The event's repository must match at least one pattern. * `scope.user_matchers`: The event's user must match at least one pattern. Within a list, any match counts. When you set both lists, both must match. A policy without a scope applies to every event, and an event that misses the scope skips the policy for both allowlists and blocklists. The policy form does not expose scope fields yet, but editing a scoped policy in the form preserves its scope. Repository scoping does not yet take effect for Claude Code sessions, which report no repository value. User scoping works across agents today. Scope differs from the **Session Posture** template: a session policy matches session events only, while a scope restricts a policy of any template. ## Out-of-the-box policies Every namespace inherits these system policies. Most ship enabled by default and appear in the **Agent Governance** policy list next to the policies you create, under the exact names shown below. An override matches on the policy name, so use these names verbatim when you override one. To change a policy for a namespace, override it instead of deleting it. See [Policy propagation across namespaces](#policy-propagation-across-namespaces) to scope an override. ### MCP server policies These policies govern MCP server and tool calls. ### Command execution policies These policies govern the shell commands an agent runs. Blocked commands stop outright. The rest ask the developer to confirm. ### File access policies These policies block access to sensitive paths. They match reads, writes, edits, and deletes, unless noted. ### Package Firewall bypass protection These policies stop an agent from bypassing the Endor Labs Package Firewall by changing where a package manager fetches packages. They ship enabled and block on a match. The table groups the protection by theme. The **Agent Governance** policy list shows the 10 underlying system policies under their own names, each prefixed with `Package Firewall`. ### Malware protection This policy runs the [malware check](/agent-governance/secure-coding#malware-check) instead of matching authored patterns. ## View, edit, or delete a policy 1. Select **User menu** > **Policies & Rules** from the left sidebar, then select **Agent Governance**. 2. Select the policy name to open its full configuration. 3. To change the policy, edit any field and click **Update Agent Governance Policy**. 4. To remove the policy, confirm in the **Delete this Policy?** prompt. Hooks pick up the deletion at the next session start. Every policy has a shareable URL that includes the namespace and policy name, so you can send a teammate a direct link to a specific policy. ## Local policy cache When the agent starts a session, [endorctl ai-audit](/developers-api/cli/commands/ai-audit) pulls a snapshot of your policies and writes it to `~/.endorctl/aigovernance/endor-policies.jsonl`. The hook evaluates every event in that session against the cached snapshot, so pattern-based enforcement happens without a network round-trip. Malware policies are the exception: a matching install triggers a live malware feed lookup, and the check fails open if the feed is unreachable. The cache file uses one JSON object per line, each representing a single policy. You do not need to edit it. If the policy download fails at session start, the hook keeps the last snapshot it fetched, so your overrides stay in effect. Policy edits take effect at the next session start. New and edited policies take effect on a developer's machine the next time the agent starts a session and refreshes the local policy cache. Tell developers to restart the agent (or open a new session) to pick up policy edits. ## Policy propagation across namespaces Policies you create in a namespace automatically propagate to its sub-namespaces. The policy form always saves with propagation on, so any policy you save in `acme` shows up for `acme.team-a`, `acme.team-a.proj-1`, and every other descendant. Through the REST API, set the `propagate` field to `false` to keep a policy out of sub-namespaces. When the **Agent Governance** policy list loads for a namespace, it returns: * Policies authored in that exact namespace. * Policies authored in any ancestor namespace. * In-built system policies that Endor Labs ships. If two policies share the same name across these layers, the closest match wins. For namespace `acme.team-a.proj-1`, a policy named `block-rm-rf` saved in `acme.team-a` overrides the same name in `acme` or the system catalog. A copy saved in `acme.team-a.proj-1` itself overrides all three. Use this to scope a change narrowly: * To turn a system or inherited policy off in one namespace, toggle it off from the **Agent Governance** policy list. This creates a local override in that namespace and leaves the policy unchanged in ancestors and siblings. * To change a system or inherited policy, override it: save a policy with the same name in the namespace where you want the change. Use a team's namespace to scope it to that team, or the tenant root to apply it tenant-wide. * Toggle a system policy off rather than trying to delete it. ## Next steps Continue with the following pages: * See [Deploy hooks for Cursor](/agent-governance/cursor), [Claude Code](/agent-governance/claude-code), [Codex](/agent-governance/codex), or [GitHub Copilot](/agent-governance/copilot) to put your policies in front of agent activity. * See [Triage policy violations](/agent-governance/policy-violations) to set your daily review workflow. # Triage policy violations Source: https://docs.endorlabs.com/agent-governance/policy-violations/index Read the summary breakdowns and the per-event table to confirm enforcement is working and investigate any policy match. **Policy Violations** records every event that matched a policy on a developer's machine. Use the page to confirm enforcement is working, investigate a single incident, and plan the next policies you write. ## Open Policy Violations Select **Agent Governance** from the left sidebar, then select **Policy Violations**. The page opens with three summaries above a per-event table. Use **Time Range** at the top to scope every summary and the table to the same window. Policy Violations ## Summary at a glance Above the violation table, the page shows three summaries: * **Top 5 Policies**: A ranked breakdown of the busiest match-category and agent combinations. * **Blocked & Alerted**: A breakdown of how violations resolved, with the total in the center. * **Violations This Week**: The seven-day count, a comparison against last week, and a per-day breakdown. **Top 5 Policies** ranks match-category and agent combinations, not individual policy names. Read the table to find specific policies. ## Filter results Use the filters above the table to narrow the rows. * **Time Range** scopes to the last hour, day, week, or a custom window. * **Category** scopes to a single activity type: **Dangerous Command**, **File Access**, **MCP Tool Call**, **MCP Server**, **Skill**, **Session**, **Malware**, or **Secret**. * **Agent** scopes to one agent: **Cursor**, **Claude Code**, **Codex**, or **GitHub Copilot**. For example, filtering by **Category: File Access** narrows the view to file-operation policy matches: Policy Violations filtered to File Access ## Read a violation Each row begins with an icon for the action the policy applied. Hover the icon to see whether the action was **Blocked**, **Alert**, or **Ask**. The following table describes the rest of the columns. ## Common triage workflows ### Confirm a new policy is working After you create a policy, ask one developer to perform an action that matches the policy. Set **Time Range** to the last hour and **Agent** to that developer's agent. Confirm the violation appears with the expected **Blocked**, **Alert**, or **Ask** action. ### Investigate a single incident Set **Time Range** to the suspected window. Browse the rows for the developer's agent and user. Hover the **Details** cell to read the full command, file path, or MCP tool name. ### Spot patterns to write new policies Filter on **Category** to find clusters of unsanctioned activity. For example, several **MCP Tool Call** rows from the same MCP server are a signal to add an **MCP Server Access** policy. A wide spread of **Dangerous Command** rows like the one below points to a missing **Command Execution** policy. Policy Violations filtered to Dangerous Command ## When no violations match **Policy Violations** shows **No Policy Violations found** when nothing matched the current filters. If you expected matches to appear, work through the following checks: * Widen **Time Range** in case the filter window is too narrow. * Check hook health on the developer machines you expect to govern. See [Deploy hooks for Cursor](/agent-governance/cursor) or [Deploy hooks for Claude Code](/agent-governance/claude-code). * Confirm a policy exists for the activity you expected to match. See [Write a policy](/agent-governance/policies) to create one. ## Next steps Continue with the following pages: * See [Read the Coding Agent Governance overview](/agent-governance/overview) for how violations trend across your fleet. * See [Write a policy](/agent-governance/policies) to add or refine patterns based on what you find. # Prerequisites for Coding Agent Governance Source: https://docs.endorlabs.com/agent-governance/prerequisites/index Set up the role, API key, and tenant settings an admin needs before any developer machine runs a Coding Agent Governance hook. Coding Agent Governance is admin-driven. Before a developer machine can send a single event, an admin must turn on the feature and issue an API key with the right role. The admin then rolls hooks out to the supported coding agents in each developer environment. In-built policies ship enabled, so basic enforcement starts as soon as hooks run. You review the catalog and add custom rules after deployment. Complete the following tasks to set up Coding Agent Governance. 1. Confirm Coding Agent Governance is available in your tenant. 2. Create an API key with the **AI Audit User** role to ship with hooks. 3. Deploy hooks on developer machines. See [Deploy hooks for Cursor](/agent-governance/cursor), [Claude Code](/agent-governance/claude-code), [Codex](/agent-governance/codex), and [GitHub Copilot](/agent-governance/copilot). 4. Review in-built policies and write any custom rules your organization needs. See [Write a policy](/agent-governance/policies). Skipping any step delays results. Inventory and policy enforcement both need hooks to run. The in-built policy catalog enforces as soon as hooks ship. Custom policies layer on top for organization-specific rules. ## Confirm Coding Agent Governance is available Select **Agent Governance** from the left sidebar. If the entry is missing, contact your account team to enable Coding Agent Governance for your tenant. ## Create an API key with the AI Audit User role The **AI Audit User** role is a least-privilege system role for Coding Agent Governance hooks. An API key with this role can submit hook events, read your policy snapshot for local evaluation, read the Coding Agent Governance inventory, and write operational client logs. It cannot read policy violations or any Endor Labs data outside Coding Agent Governance. Treat the API key and secret as production credentials. Any host with these values can submit hook events as your tenant. ### Create the API key through the user interface 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control**. 3. Select **API Keys**, then click **Generate API Key**. 4. Enter a name that identifies the key, such as `agent-governance-hooks`. 5. Under **Role**, choose **AI Audit User**. 6. Choose an expiration that matches your rotation policy. 7. Click **Generate**, then copy the key and secret. Store both in your secret manager. Endor Labs shows the secret only once. See [Manage API keys](/platform-administration/api-keys) to manage this key over time. ### Create the API key with endorctl For MDM-driven rollouts or automated provisioning, create the key with [endorctl](/setup-deployment/cli). Replace `` with the namespace that owns your Coding Agent Governance policies, `` with a descriptive name for the key, and `` with the expiration in ISO 8601 UTC format. ```bash theme={null} endorctl api create -r APIKey -n "" --data '{ "meta": { "name": "" }, "spec": { "permissions": { "roles": ["SYSTEM_ROLE_AI_AUDIT"] }, "expiration_time": "" }, "propagate": true }' ``` The response contains the API key and secret under `spec.key` and `spec.secret`. Capture both before the response scrolls out of your terminal. Endor Labs returns the secret only once. See [Create an API key through Endor Labs API](/platform-administration/api-keys#create-an-api-key-through-endor-labs-api) for the full API reference, including longer expirations and namespace propagation. ## Data collection Each hook event carries the metadata Endor Labs needs for inventory and policy evaluation: * Agent name, version, and (where available) model * Session and sub-session IDs * Device (endpoint) identifier * Session configuration, such as permission mode and sandbox state * User identifier when the agent provides one * Repository name (not populated for Claude Code sessions) and working directory * MCP server name, tool name, and call counts * Shell command line (regex-matched against your policies) * File path and operation type (read, write, delete, edit) * Secrets check match (rule, line, column, and fingerprint, never the secret value) * Policy match outcome and the action applied ### Secret redaction Endor Labs runs every command line, file path, URL, environment value, and MCP tool input or output through a regex-based redactor before it leaves the developer's machine. Environment variables and keys named like a secret (such as `TOKEN`, `SECRET`, `API_KEY`, `PASSWORD`, or `AUTHORIZATION`) become `[REDACTED]`. The redactor also matches common secret formats in place: URL and database-connection credentials, AWS access keys, JWTs, PEM private keys, and provider tokens such as GitHub (`ghp_*`), OpenAI, and Anthropic keys. Redaction of event payloads is best-effort regex pattern matching. A secret that does not match a known pattern or key name can still reach the backend. The [secrets check](/agent-governance/secure-coding) is separate from redaction: it detects secrets in file content on the developer's machine, and its violations carry the rule and location, never the value. On Cursor, the `sessionStart` hook returns the Endor Labs credential values to Cursor in plaintext under an `AGENT_HOOK_ENDOR_*` prefix, so subsequent hooks in the session inherit them. The values never leave the developer's machine, but anything that captures Cursor hook stdout (such as debug logging or screen recording) can see them. ## Distribute credentials to developer machines Hooks read credentials from environment variables wherever they run: * `ENDOR_API`: The Endor Labs API endpoint, for example `https://api.endorlabs.com`. * `ENDOR_NAMESPACE`: The Endor Labs namespace that owns the policies and receives the events. * `ENDOR_API_CREDENTIALS_KEY`: The API key value. * `ENDOR_API_CREDENTIALS_SECRET`: The API secret. For Cursor, Codex, and GitHub Copilot, set the variables in the environment that launches the agent. For Claude Code, set them in the `env` block of `settings.json`, as shown on [Deploy hooks for Claude Code](/agent-governance/claude-code). Use your MDM (Jamf, Intune, Kandji, JumpCloud) to deliver the values, and to ensure endorctl is on `PATH`, on every machine that runs an Endor Labs hook. Do not distribute `ENDOR_TOKEN` alongside these variables. Hooks authenticate with the API key and secret only, and on older versions of endorctl the extra token triggered a mixed-authentication error that blocked `endorctl ai-audit`. See [endorctl CLI](/setup-deployment/cli) to install endorctl. ## Confirm supported agents and platforms Coding Agent Governance hooks support Cursor, Claude Code, Codex, and GitHub Copilot on macOS, Linux, and Windows developer machines. See [Supported agents and platforms](/agent-governance#supported-agents-and-platforms) for the full matrix, including hosted and CLI form factors. ## Next steps After you complete the prerequisites, proceed to the next steps: * See [Deploy hooks for Cursor](/agent-governance/cursor), [Claude Code](/agent-governance/claude-code), [Codex](/agent-governance/codex), and [GitHub Copilot](/agent-governance/copilot) to roll hooks out. * See [Write a policy](/agent-governance/policies) to review the in-built catalog and add organization-specific rules. # Secure coding checks Source: https://docs.endorlabs.com/agent-governance/secure-coding/index Catch malicious packages and leaked secrets in the agent loop, backed by Endor Labs intelligence. Secure coding checks are Coding Agent Governance policies that inspect what an AI coding agent produces, not just the shape of its actions. Two checks are available: a malware check for the packages an agent installs, and a secrets check for the content it writes and reads. Both run in the agent loop, so they catch problems at the moment they happen instead of in a later scan. Other Coding Agent Governance policies match patterns you author, such as regex patterns for commands and file paths. Secure coding checks carry no patterns to maintain. The policy decides when the check runs and which action follows a match. The verdict comes from Endor Labs data: the malware feed for packages, and the secret detection rules library for content. ## Malware check The malware check fires when a governed agent installs a package. The check looks up the package in the Endor Labs malware feed, the same intelligence that powers [malicious package detection](/scan/malware) and [Package Firewall](/package-firewall). Only confirmed malware triggers the policy. Contested records and records under review do not. A malware violation carries the evidence your team needs to respond: * The package name, version, and ecosystem from the install. An unpinned install shows an empty version. * A summary of the malware report and the reasons the feed flagged the package. * The feed source that flagged the package. A malware check applies to all ecosystems by default. To limit a policy to specific ecosystems, such as npm or PyPI, set its `ecosystems` list through the REST API. The policy form does not expose secure coding fields yet. The following example creates a malware policy scoped to npm and PyPI installs with [endorctl](/developers-api/cli/commands/api). Replace `` with the namespace that owns your Coding Agent Governance policies. Leave `ecosystems` empty to check every ecosystem. ```bash theme={null} endorctl api create -r AgentHookPolicyDefinition -n "" --data '{ "meta": { "name": "malware-check-npm-pypi" }, "spec": { "policy": { "name": "Malware check: npm and PyPI installs", "enabled": true, "activity": { "malware_check": { "ecosystems": ["npm", "pypi"] } }, "action": { "match_type": "MATCH_TYPE_BLOCKLIST", "block": { "message": "Endor Labs flagged this package as malware." } } } }, "propagate": true }' ``` The policy appears under **Policies & Rules** > **Agent Governance**, and hooks pick it up at the next session start. ## Secrets check The secrets check scans content the agent writes or reads for secrets, such as cloud access keys, provider tokens, and private keys. Detection uses the Endor Labs secret rules library, the same rules as [secrets scanning](/scan/secrets). See [Secret detection rules](/scan/secrets/secret-rules) for the full library. The scan runs on the developer's machine, and the scanned content never leaves it. A secrets violation carries: * The rule that fired, such as `aws-access-token` or `github-pat`, with its human-readable name. * The line and column where the secret starts. * A fingerprint that groups repeat findings of the same secret. The violation never includes the secret value. The record has no field for it, so a match can't leak the credential it found. By default the check scans every file the event covers. Through the REST API, `include_file_patterns` limits scanning to matching paths, and `exclude_file_patterns` skips paths such as test fixtures or vendored directories. Exclusions apply after inclusions. To create a secrets policy, follow the [malware policy example](#malware-check) with a `secrets_check` activity in place of `malware_check`. ## Actions Secure coding checks use the same actions as every other Coding Agent Governance policy: **Block** stops the action, **Alert** records it, and **Ask Permission** pauses for the developer. Violations appear under **Policy Violations** next to the rest of your governance activity. See [Actions](/agent-governance/policies#actions) for what the developer and your security team see for each action. ## How the checks fit with other Endor Labs protection Endor Labs catches malicious packages and secrets at more than one layer, and each layer covers a different point in the workflow: * Secure coding checks act in the agent loop, at the moment an agent installs a package or touches a secret. * [Package Firewall](/package-firewall) protects the registry path for every install in your organization, whether an agent or a person runs it. * [Secrets scanning](/scan/secrets) finds secrets already committed to your repositories and pull requests. The layers share the same intelligence, so a package blocked in the agent loop is the same one Package Firewall blocks at the registry. ## Limitations Be aware of the following limitations: * Checks run for [supported agents](/agent-governance#supported-agents-and-platforms) on machines with hooks deployed. * The secrets check inspects content the agent touches in a session. It is not a repository-wide scan. Use [secrets scanning](/scan/secrets) for full-repository coverage. * Like all Coding Agent Governance controls, these checks are guardrails for agent behavior, not a security boundary. See [What Coding Agent Governance is (and isn't)](/agent-governance/how-it-works#what-coding-agent-governance-is-and-isnt). # ListAgentActivity Source: https://docs.endorlabs.com/api-reference/agenttelemetryservice/listagentactivity /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/agent-telemetry/activity Returns the per-agent usage summary for a tenant. # ListAgentCalls Source: https://docs.endorlabs.com/api-reference/agenttelemetryservice/listagentcalls /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/agent-telemetry/agents/{agent_id}/calls Returns one agent's recent captured calls, newest first. # CreateAISastCustomerContext creates a scoped context; namespace scope is carried by tenant_meta.namespace. Source: https://docs.endorlabs.com/api-reference/aisastcustomercontextservice/createaisastcustomercontext-creates-a-scoped-context;-namespace-scope-is-carried-by-tenant_metanamespace /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/ai-sast-customer-contexts # DeleteAISastCustomerContext deletes an entry by UUID. Source: https://docs.endorlabs.com/api-reference/aisastcustomercontextservice/deleteaisastcustomercontext-deletes-an-entry-by-uuid /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/ai-sast-customer-contexts/{uuid} # GetAISastCustomerContext fetches an entry by UUID. Source: https://docs.endorlabs.com/api-reference/aisastcustomercontextservice/getaisastcustomercontext-fetches-an-entry-by-uuid /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/ai-sast-customer-contexts/{uuid} # ListAISastCustomerContexts lists entries in a namespace; filter on parent fields for tenant or project scope. Source: https://docs.endorlabs.com/api-reference/aisastcustomercontextservice/listaisastcustomercontexts-lists-entries-in-a-namespace;-filter-on-parent-fields-for-tenant-or-project-scope /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/ai-sast-customer-contexts # UpdateAISastCustomerContext updates an entry from the request body. Source: https://docs.endorlabs.com/api-reference/aisastcustomercontextservice/updateaisastcustomercontext-updates-an-entry-from-the-request-body /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/ai-sast-customer-contexts # CreateAPIKey Source: https://docs.endorlabs.com/api-reference/apikeyservice/createapikey /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/api-keys Creates an API key. # DeleteAPIKey Source: https://docs.endorlabs.com/api-reference/apikeyservice/deleteapikey /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/api-keys/{uuid} Deletes the API key specified by the UUID. # GetAPIKey Source: https://docs.endorlabs.com/api-reference/apikeyservice/getapikey /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/api-keys/{uuid} Fetches the API key dentified by the UUID. # ListAPIKeys Source: https://docs.endorlabs.com/api-reference/apikeyservice/listapikeys /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/api-keys Lists all API keys for a given namespace. # CreateAPIKeyReq Source: https://docs.endorlabs.com/api-reference/apikeyvalidatorservice/createapikeyreq /api-reference/openapi.v3.json post /v1/auth/api-key/validate Validates an API key. # CreateArtifactSignature Source: https://docs.endorlabs.com/api-reference/artifactsignatureservice/createartifactsignature /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/artifact-signatures Creates a new artifact signature. # GetArtifactSignature Source: https://docs.endorlabs.com/api-reference/artifactsignatureservice/getartifactsignature /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/artifact-signatures/{uuid} Fetches an artifact signature identified by the UUID. # ListArtifactSignatures Source: https://docs.endorlabs.com/api-reference/artifactsignatureservice/listartifactsignatures /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/artifact-signatures Lists all artifact signatures. # UpdateArtifactSignature Source: https://docs.endorlabs.com/api-reference/artifactsignatureservice/updateartifactsignature /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/artifact-signatures Updates the artifact signature. # CreateAsyncJob initiates asynchronous execution of a job. The caller must have permission to create async jobs of the requested type. Returns immediately with the job UUID and state=JOB_STATE_NEW; poll GetAsyncJob to track progress. Source: https://docs.endorlabs.com/api-reference/asyncjobservice/createasyncjob-initiates-asynchronous-execution-of-a-job-thecaller-must-have-permission-to-create-async-jobs-of-the-requestedtype-returns-immediately-with-the-job-uuid-andstate=job_state_new;-poll-getasyncjob-to-track-progress /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/async-jobs # GetAsyncJob fetches an async job by UUID. Returns 404 if no async job with that UUID exists. When state = JOB_STATE_SUCCESS, spec.response carries the type-specific arm (sbom or vex) with a freshly signed download URL (5-minute TTL) and the stable object-store file_path. Source: https://docs.endorlabs.com/api-reference/asyncjobservice/getasyncjob-fetches-an-async-job-by-uuid-returns-404-if-no-async-jobwith-that-uuid-exists-when-state-=-job_state_success-specresponsecarries-the-type-specific-arm-sbom-or-vex-with-a-freshly-signeddownload-url-5-minute-ttl-and-the-stable-object-store-file_path /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/async-jobs/{uuid} # GetAuditLog Source: https://docs.endorlabs.com/api-reference/auditlogservice/getauditlog /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/audit-logs/{uuid} Fetches an audit log identified by the UUID. # ListAuditLogs Source: https://docs.endorlabs.com/api-reference/auditlogservice/listauditlogs /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/audit-logs List all audit logs in a given namespace. # CreateAuthenticationLog Source: https://docs.endorlabs.com/api-reference/authenticationlogservice/createauthenticationlog /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/authentication-logs Creates an authentication log for a given object. # DeleteAuthenticationLog Source: https://docs.endorlabs.com/api-reference/authenticationlogservice/deleteauthenticationlog /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/authentication-logs/{uuid} Deletes the authentication log specified by its UUID. # GetAuthenticationLog Source: https://docs.endorlabs.com/api-reference/authenticationlogservice/getauthenticationlog /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/authentication-logs/{uuid} Fetches the authentication log identified by the UUID. # ListAuthenticationLogs Source: https://docs.endorlabs.com/api-reference/authenticationlogservice/listauthenticationlogs /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/authentication-logs Lists all authentication logs in a given namespace. # Authenticate Source: https://docs.endorlabs.com/api-reference/authenticationservice/authenticate /api-reference/openapi.v3.json get /v1/auth/{authentication_source} Initiates an authentication request and returns a token along with the token expiration time for an authenticated user. # Logout Source: https://docs.endorlabs.com/api-reference/authenticationservice/logout /api-reference/openapi.v3.json get /v1/auth/{authentication_source}/logout Clears the user session and cookies. # CreateAuthorizationPolicy Source: https://docs.endorlabs.com/api-reference/authorizationpolicyservice/createauthorizationpolicy /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/authorization-policies Creates an authorization policy for a given tenant. # DeleteAuthorizationPolicy Source: https://docs.endorlabs.com/api-reference/authorizationpolicyservice/deleteauthorizationpolicy /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/authorization-policies/{uuid} Deletes an authorization policy specified by its UUID. # GetAuthorizationPolicy Source: https://docs.endorlabs.com/api-reference/authorizationpolicyservice/getauthorizationpolicy /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/authorization-policies/{uuid} Fetches an authorization policy specified by its UUID. # ListAuthorizationPolicies Source: https://docs.endorlabs.com/api-reference/authorizationpolicyservice/listauthorizationpolicies /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/authorization-policies Lists all authorization policies for a given tenant. # UpdateAuthorizationPolicy Source: https://docs.endorlabs.com/api-reference/authorizationpolicyservice/updateauthorizationpolicy /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/authorization-policies Updates the authorization policy for a given tenant. # CreateBatchFileSegments Source: https://docs.endorlabs.com/api-reference/batchfilesegmentsservice/createbatchfilesegments /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/batch/file-segments Create multiple file segment objects through a batch API call. # CreateBatchNotification Source: https://docs.endorlabs.com/api-reference/batchnotificationservice/createbatchnotification /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/batch/notifications Create multiple notification objects through a batch API call. # GetCallGraphData Source: https://docs.endorlabs.com/api-reference/callgraphdataservice/getcallgraphdata /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/call-graph-data/{uuid} Fetches the call graph for a given package version that is captured in the parent UUID. # ListCallGraphData Source: https://docs.endorlabs.com/api-reference/callgraphdataservice/listcallgraphdata /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/call-graph-data Lists all call graph data in a namespace. # GetCodeOwners Source: https://docs.endorlabs.com/api-reference/codeownersservice/getcodeowners /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/codeowners/{uuid} Fetches the CodeOwners object identified by the UUID. # ListCodeOwners Source: https://docs.endorlabs.com/api-reference/codeownersservice/listcodeowners /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/codeowners Lists all CodeOwners objects in a namespace. # GetDependencyMetadata Source: https://docs.endorlabs.com/api-reference/dependencymetadataservice/getdependencymetadata /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/dependency-metadata/{uuid} Returns a specified dependency metadata object. # ListDependencyMetadata Source: https://docs.endorlabs.com/api-reference/dependencymetadataservice/listdependencymetadata /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/dependency-metadata List dependency metadata objects based on the specified list parameters. # CreateEndorIgnoreEntry Source: https://docs.endorlabs.com/api-reference/endorignoreentryservice/createendorignoreentry /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/endor-ignore-entries Creates an EndorIgnoreEntry object. # DeleteEndorIgnoreEntry Source: https://docs.endorlabs.com/api-reference/endorignoreentryservice/deleteendorignoreentry /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/endor-ignore-entries/{uuid} Deletes the EndorIgnoreEntry object identified by the UUID. # GetEndorIgnoreEntry Source: https://docs.endorlabs.com/api-reference/endorignoreentryservice/getendorignoreentry /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/endor-ignore-entries/{uuid} Fetches the EndorIgnoreEntry object identified by the UUID. # ListEndorIgnoreEntries Source: https://docs.endorlabs.com/api-reference/endorignoreentryservice/listendorignoreentries /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/endor-ignore-entries Lists all EndorIgnoreEntry objects in a namespace. # UpdateEndorIgnoreEntry Source: https://docs.endorlabs.com/api-reference/endorignoreentryservice/updateendorignoreentry /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/endor-ignore-entries Updates the EndorIgnoreEntry object identified by the UUID. # CreateExporter Source: https://docs.endorlabs.com/api-reference/exporterservice/createexporter /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/exporters Creates a exporter. # DeleteExporter Source: https://docs.endorlabs.com/api-reference/exporterservice/deleteexporter /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/exporters/{uuid} Deletes the exporter specified by the UUID. # GetExporter Source: https://docs.endorlabs.com/api-reference/exporterservice/getexporter /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/exporters/{uuid} Fetches the exporter identified by the UUID. # ListExporters Source: https://docs.endorlabs.com/api-reference/exporterservice/listexporters /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/exporters Lists all exporters. # UpdateExporter Source: https://docs.endorlabs.com/api-reference/exporterservice/updateexporter /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/exporters Updates a exporter. # GetFindingLog Source: https://docs.endorlabs.com/api-reference/findinglogservice/getfindinglog /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/finding-logs/{uuid} Returns a specified finding log. # ListFindingLogs Source: https://docs.endorlabs.com/api-reference/findinglogservice/listfindinglogs /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/finding-logs Returns a list of finding logs based on the specified list parameters. # DeleteFinding Source: https://docs.endorlabs.com/api-reference/findingservice/deletefinding /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/findings/{uuid} Delete the finding specified by the UUID. # GetFinding Source: https://docs.endorlabs.com/api-reference/findingservice/getfinding /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/findings/{uuid} Fetch the finding identified by the UUID. # ListFindings Source: https://docs.endorlabs.com/api-reference/findingservice/listfindings /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/findings List findings based on the specified list parameters. # UpdateFinding Source: https://docs.endorlabs.com/api-reference/findingservice/updatefinding /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/findings Update a specified finding. # GetHuggingFaceModel Source: https://docs.endorlabs.com/api-reference/huggingfacemodelservice/gethuggingfacemodel /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/hugging-face-models/{uuid} Fetches the HuggingFace model specified by the UUID. # ListHuggingFaceModels Source: https://docs.endorlabs.com/api-reference/huggingfacemodelservice/listhuggingfacemodels /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/hugging-face-models Lists all HuggingFace models in a given namespace. # GetHuggingFaceOrganization Source: https://docs.endorlabs.com/api-reference/huggingfaceorganizationservice/gethuggingfaceorganization /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/hugging-face-organizations/{uuid} Fetches the HuggingFace organization specified by the UUID. # ListHuggingFaceOrganizations Source: https://docs.endorlabs.com/api-reference/huggingfaceorganizationservice/listhuggingfaceorganizations /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/hugging-face-organizations Lists all HuggingFace organizations in a given namespace. # CreateIdentityProvider Source: https://docs.endorlabs.com/api-reference/identityproviderservice/createidentityprovider /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/identity-providers Creates an identity provider. # DeleteIdentityProvider Source: https://docs.endorlabs.com/api-reference/identityproviderservice/deleteidentityprovider /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/identity-providers/{uuid} Deletes the identity provider specified by the UUID. # GetIdentityProvider Source: https://docs.endorlabs.com/api-reference/identityproviderservice/getidentityprovider /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/identity-providers/{uuid} Fetches the identity provider specified by the UUID. # ListIdentityProviders Source: https://docs.endorlabs.com/api-reference/identityproviderservice/listidentityproviders /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/identity-providers Lists all identity providers. # UpdateIdentityProvider Source: https://docs.endorlabs.com/api-reference/identityproviderservice/updateidentityprovider /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/identity-providers Updates an identity provider. # CreateInstallation Source: https://docs.endorlabs.com/api-reference/installationservice/createinstallation /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/installations creates a installation. The creation of the resource will be an upsert if the given spec.external_id and spec.platform_resource were already created. # DeleteInstallation Source: https://docs.endorlabs.com/api-reference/installationservice/deleteinstallation /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/installations/{uuid} Deletes an installation specified by the UUID. # GetInstallation Source: https://docs.endorlabs.com/api-reference/installationservice/getinstallation /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/installations/{uuid} Fetches an installation identified by the UUID. # ListInstallations Source: https://docs.endorlabs.com/api-reference/installationservice/listinstallations /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/installations Lists all installations. # UpdateInstallation Source: https://docs.endorlabs.com/api-reference/installationservice/updateinstallation /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/installations Updates an installation. # CreateInvitation Source: https://docs.endorlabs.com/api-reference/invitationservice/createinvitation /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/invitations Creates an invitation. # DeleteInvitation Source: https://docs.endorlabs.com/api-reference/invitationservice/deleteinvitation /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/invitations/{uuid} Deletes the invitation specified by the UUID # GetInvitation Source: https://docs.endorlabs.com/api-reference/invitationservice/getinvitation /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/invitations/{uuid} Fetches the invitation identified by the UUID. # ListInvitations Source: https://docs.endorlabs.com/api-reference/invitationservice/listinvitations /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/invitations Lists the invitations in a namespace. # CreateIPAddressPolicy Source: https://docs.endorlabs.com/api-reference/ipaddresspolicyservice/createipaddresspolicy /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/ip-address-policies Creates a finding log. # GetIPAddressPolicy Source: https://docs.endorlabs.com/api-reference/ipaddresspolicyservice/getipaddresspolicy /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/ip-address-policies/{uuid} Returns a specified finding log. # ListIPAddresssPolicies Source: https://docs.endorlabs.com/api-reference/ipaddresspolicyservice/listipaddressspolicies /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/ip-address-policies Returns a list of finding logs based on the specified list parameters. # CreateLicenseDependency Source: https://docs.endorlabs.com/api-reference/licensedependencyservice/createlicensedependency /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/license-dependencies Creates a license dependency. # DeleteLicenseDependency Source: https://docs.endorlabs.com/api-reference/licensedependencyservice/deletelicensedependency /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/license-dependencies/{uuid} Deletes the license dependency specified by the UUID. # GetLicenseDependency Source: https://docs.endorlabs.com/api-reference/licensedependencyservice/getlicensedependency /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/license-dependencies/{uuid} Fetches the license dependency specified by the UUID. # ListLicenseDependencies Source: https://docs.endorlabs.com/api-reference/licensedependencyservice/listlicensedependencies /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/license-dependencies Lists all the license dependencies in a given namespace. # UpdateLicenseDependency Source: https://docs.endorlabs.com/api-reference/licensedependencyservice/updatelicensedependency /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/license-dependencies Updates the license dependency. # GenerateLicenseNoticesReport Source: https://docs.endorlabs.com/api-reference/licensenoticesreportservice/generatelicensenoticesreport /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/license-notices-reports Creates a license notices report. # CreateLicenseSummary Source: https://docs.endorlabs.com/api-reference/licensesummaryservice/createlicensesummary /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/license-summaries Creates a license summary. # DeleteLicenseSummary Source: https://docs.endorlabs.com/api-reference/licensesummaryservice/deletelicensesummary /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/license-summaries/{uuid} Deletes the license summary specified by the UUID. # GetLicenseSummary Source: https://docs.endorlabs.com/api-reference/licensesummaryservice/getlicensesummary /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/license-summaries/{uuid} Fetches the license summary specified by the UUID. # ListLicenseSummaries Source: https://docs.endorlabs.com/api-reference/licensesummaryservice/listlicensesummaries /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/license-summaries Lists all the license summaries in a given namespace. # UpdateLicenseSummary Source: https://docs.endorlabs.com/api-reference/licensesummaryservice/updatelicensesummary /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/license-summaries Updates the license summary. # GetLinterResult Source: https://docs.endorlabs.com/api-reference/linterresultservice/getlinterresult /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/linter-results/{uuid} Fetches the linter result identified by the UUID. # ListLinterResults Source: https://docs.endorlabs.com/api-reference/linterresultservice/listlinterresults /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/linter-results Lists all linter results. # CreateMalwareExposureQuery Source: https://docs.endorlabs.com/api-reference/malwareexposurequeryservice/createmalwareexposurequery /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/queries/malware-exposure Creates a MalwareExposureQuery. # CreateMalwareExposure Source: https://docs.endorlabs.com/api-reference/malwareexposureservice/createmalwareexposure /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/malware-exposure Creates a MalwareExposure object. # DeleteMalwareExposure Source: https://docs.endorlabs.com/api-reference/malwareexposureservice/deletemalwareexposure /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/malware-exposure/{uuid} Deletes the MalwareExposure object specified by the UUID. # GetMalwareExposure Source: https://docs.endorlabs.com/api-reference/malwareexposureservice/getmalwareexposure /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/malware-exposure/{uuid} Fetches the MalwareExposure object identified by the UUID. # ListMalwareExposure Source: https://docs.endorlabs.com/api-reference/malwareexposureservice/listmalwareexposure /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/malware-exposure Lists all MalwareExposure objects in a namespace. # UpdateMalwareExposure Source: https://docs.endorlabs.com/api-reference/malwareexposureservice/updatemalwareexposure /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/malware-exposure Updates the MalwareExposure object specified by the UUID. # GetMalware Source: https://docs.endorlabs.com/api-reference/malwareservice/getmalware /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/malware/{uuid} Fetches a malware identified by the UUID. # ListMalware Source: https://docs.endorlabs.com/api-reference/malwareservice/listmalware /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/malware List all malware in the namespace. # GetMetric Source: https://docs.endorlabs.com/api-reference/metricservice/getmetric /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/metrics/{uuid} Fetches a metric specified by its UUID. # ListMetrics Source: https://docs.endorlabs.com/api-reference/metricservice/listmetrics /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/metrics Lists all metrics in a specified namespace. # CreateNamespace Source: https://docs.endorlabs.com/api-reference/namespaceservice/createnamespace /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/namespaces Creates a namespace. # DeleteNamespace Source: https://docs.endorlabs.com/api-reference/namespaceservice/deletenamespace /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/namespaces/{uuid} Deletes a namespace based on its UUID. # GetNamespace Source: https://docs.endorlabs.com/api-reference/namespaceservice/getnamespace /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/namespaces/{uuid} Fetches a namespace identified by its UUID. # ListNamespaces Source: https://docs.endorlabs.com/api-reference/namespaceservice/listnamespaces /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/namespaces Lists all namespaces in a tenant. # UpdateNamespace Source: https://docs.endorlabs.com/api-reference/namespaceservice/updatenamespace /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/namespaces Updates a provided namespace based on its UUID. # UpdateNamespace Source: https://docs.endorlabs.com/api-reference/namespaceservice/updatenamespace-1 /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/namespaces/{object.uuid}/namespaces Updates a provided namespace based on its UUID. # GetNotification Source: https://docs.endorlabs.com/api-reference/notificationservice/getnotification /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/notifications/{uuid} Fetches the notification identified by the UUID. # ListNotifications Source: https://docs.endorlabs.com/api-reference/notificationservice/listnotifications /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/notifications List all notifications. # CreateNotificationTarget Source: https://docs.endorlabs.com/api-reference/notificationtargetservice/createnotificationtarget /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/notification-targets Creates a notification target. # DeleteNotificationTarget Source: https://docs.endorlabs.com/api-reference/notificationtargetservice/deletenotificationtarget /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/notification-targets/{uuid} Deletes the notification target specified by the UUID. # GetNotificationTarget Source: https://docs.endorlabs.com/api-reference/notificationtargetservice/getnotificationtarget /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/notification-targets/{uuid} Fetches the notification target identified by the UUID. # ListNotificationTargets Source: https://docs.endorlabs.com/api-reference/notificationtargetservice/listnotificationtargets /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/notification-targets Lists all notification targets. # UpdateNotificationTarget Source: https://docs.endorlabs.com/api-reference/notificationtargetservice/updatenotificationtarget /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/notification-targets Updates a notification target. # CreateOnPremScheduler creates an onprem scheduler. Source: https://docs.endorlabs.com/api-reference/onpremschedulerservice/createonpremscheduler-creates-an-onprem-scheduler /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/onprem-schedulers # DeleteOnPremScheduler deletes an onprem scheduler specified by its UUID. Source: https://docs.endorlabs.com/api-reference/onpremschedulerservice/deleteonpremscheduler-deletes-an-onprem-scheduler-specified-by-its-uuid /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/onprem-schedulers/{uuid} # GetOnPremScheduler returns an onprem scheduler specified by its UUID. Source: https://docs.endorlabs.com/api-reference/onpremschedulerservice/getonpremscheduler-returns-an-onprem-scheduler-specified-by-its-uuid /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/onprem-schedulers/{uuid} # ListOnPremSchedulers returns a list of onprem schedulers in a specified namespace. Source: https://docs.endorlabs.com/api-reference/onpremschedulerservice/listonpremschedulers-returns-a-list-of-onprem-schedulers-in-a-specified-namespace /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/onprem-schedulers # UpdateOnPremScheduler updates the specified onprem scheduler. Source: https://docs.endorlabs.com/api-reference/onpremschedulerservice/updateonpremscheduler-updates-the-specified-onprem-scheduler /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/onprem-schedulers # GetPackageFirewallLog Source: https://docs.endorlabs.com/api-reference/packagefirewalllogservice/getpackagefirewalllog /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/package-firewall-logs/{uuid} Fetches the package firewall log identified by the UUID. # ListPackageFirewallLogs Source: https://docs.endorlabs.com/api-reference/packagefirewalllogservice/listpackagefirewalllogs /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/package-firewall-logs Lists all package firewall logs in a given namespace. # CreatePackageLicenseOverride Source: https://docs.endorlabs.com/api-reference/packagelicenseoverrideservice/createpackagelicenseoverride /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/package-license-overrides Creates a package license override. # DeletePackageLicenseOverride Source: https://docs.endorlabs.com/api-reference/packagelicenseoverrideservice/deletepackagelicenseoverride /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/package-license-overrides/{uuid} Deletes a specified package license override. # GetPackageLicenseOverride Source: https://docs.endorlabs.com/api-reference/packagelicenseoverrideservice/getpackagelicenseoverride /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/package-license-overrides/{uuid} Gets a package license override by its UUID. # ListPackageLicenseOverrides Source: https://docs.endorlabs.com/api-reference/packagelicenseoverrideservice/listpackagelicenseoverrides /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/package-license-overrides Lists all package license overrides in a namespace. # UpdatePackageLicenseOverride Source: https://docs.endorlabs.com/api-reference/packagelicenseoverrideservice/updatepackagelicenseoverride /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/package-license-overrides Updates a specified package license override. # CreatePackageLicenseQuery Source: https://docs.endorlabs.com/api-reference/packagelicensequeryservice/createpackagelicensequery /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/queries/package-license-queries Creates a query to fetch merged license data (PackageLicense + PackageLicenseOverride) for a package version from all the namespaces in the namespace chain. This is the primary API for the Edit Dependency UI page. The response combines: - Original licenses/copyrights/notices from PackageLicense (fetched from OSS namespace). - Any overrides from PackageLicenseOverride (fetched from user namespace). - Selection states for each item (defaults to selected if not in selection map). # CreatePackageLicense Source: https://docs.endorlabs.com/api-reference/packagelicenseservice/createpackagelicense /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/package-licenses Creates a package license. # DeletePackageLicense Source: https://docs.endorlabs.com/api-reference/packagelicenseservice/deletepackagelicense /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/package-licenses/{uuid} Deletes the package license specified by the UUID. # GetPackageLicense Source: https://docs.endorlabs.com/api-reference/packagelicenseservice/getpackagelicense /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/package-licenses/{uuid} Fetches the package license specified by the UUID. # ListPackageLicenses Source: https://docs.endorlabs.com/api-reference/packagelicenseservice/listpackagelicenses /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/package-licenses Lists all the package licenses in a given namespace. # UpdatePackageLicense Source: https://docs.endorlabs.com/api-reference/packagelicenseservice/updatepackagelicense /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/package-licenses Updates the package license. # CreatePackageManager Source: https://docs.endorlabs.com/api-reference/packagemanagerservice/createpackagemanager /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/package-managers Creates a package manager in a given namespace. # DeletePackageManager Source: https://docs.endorlabs.com/api-reference/packagemanagerservice/deletepackagemanager /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/package-managers/{uuid} Deletes a package manager specified by its UUID. # GetPackageManager Source: https://docs.endorlabs.com/api-reference/packagemanagerservice/getpackagemanager /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/package-managers/{uuid} Fetches the package manager identified by the UUID. # ListPackageManagers Source: https://docs.endorlabs.com/api-reference/packagemanagerservice/listpackagemanagers /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/package-managers Lists all package managers in a given namespace # UpdatePackageManager Source: https://docs.endorlabs.com/api-reference/packagemanagerservice/updatepackagemanager /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/package-managers Updates a specified package manager. # DeletePackageVersion Source: https://docs.endorlabs.com/api-reference/packageversionservice/deletepackageversion /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/package-versions/{uuid} Deletes a package version specified by the UUID. # GetPackageVersion Source: https://docs.endorlabs.com/api-reference/packageversionservice/getpackageversion /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/package-versions/{uuid} Fetches a package version specified by the UUID. # ListPackageVersions Source: https://docs.endorlabs.com/api-reference/packageversionservice/listpackageversions /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/package-versions Lists all the package versions in a given namespace. # UpdatePackageVersion Source: https://docs.endorlabs.com/api-reference/packageversionservice/updatepackageversion /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/package-versions Updates a specified package version. # GetPluginBinary Source: https://docs.endorlabs.com/api-reference/pluginbinaryservice/getpluginbinary /api-reference/openapi.v3.json get /v1/plugin-binaries/{uuid} Fetches a plugin binary identified by the UUID. # ListPluginBinaries Source: https://docs.endorlabs.com/api-reference/pluginbinaryservice/listpluginbinaries /api-reference/openapi.v3.json get /v1/plugin-binaries Lists all the available plugin binaries. # CreatePolicy Source: https://docs.endorlabs.com/api-reference/policyservice/createpolicy /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/policies Creates a policy. # DeletePolicy Source: https://docs.endorlabs.com/api-reference/policyservice/deletepolicy /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/policies/{uuid} Deletes the policy specified by the UUID. # GetPolicy Source: https://docs.endorlabs.com/api-reference/policyservice/getpolicy /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/policies/{uuid} Fetches the policy identified by the UUID. # ListPolicies Source: https://docs.endorlabs.com/api-reference/policyservice/listpolicies /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/policies Lists all policies in a namespace. # UpdatePolicy Source: https://docs.endorlabs.com/api-reference/policyservice/updatepolicy /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/policies Updates the policy. # GetPolicyTemplate Source: https://docs.endorlabs.com/api-reference/policytemplateservice/getpolicytemplate /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/policy-templates/{uuid} Fetches the policy template identified by the UUID. # ListPolicyTemplates Source: https://docs.endorlabs.com/api-reference/policytemplateservice/listpolicytemplates /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/policy-templates Lists all policy templates in a namespace. # CreatePRCommentConfig Source: https://docs.endorlabs.com/api-reference/prcommentconfigservice/createprcommentconfig /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/pr-comment-configs Creates a PR comment configuration. # DeletePRCommentConfig Source: https://docs.endorlabs.com/api-reference/prcommentconfigservice/deleteprcommentconfig /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/pr-comment-configs/{uuid} Deletes the PR comment configuration identified by the UUID. # GetPRCommentConfig Source: https://docs.endorlabs.com/api-reference/prcommentconfigservice/getprcommentconfig /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/pr-comment-configs/{uuid} Fetches the PR comment configuration specified by the UUID. # ListPRCommentConfigs Source: https://docs.endorlabs.com/api-reference/prcommentconfigservice/listprcommentconfigs /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/pr-comment-configs List all PR comment configurations for the tenant namespace. # UpdatePRCommentConfig Source: https://docs.endorlabs.com/api-reference/prcommentconfigservice/updateprcommentconfig /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/pr-comment-configs Updates the the PR comment configuration. # CreateProject Source: https://docs.endorlabs.com/api-reference/projectservice/createproject /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/projects Creates a project in a given namespace. # DeleteProject Source: https://docs.endorlabs.com/api-reference/projectservice/deleteproject /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/projects/{uuid} Deletes a project specified by its UUID. # GetProject Source: https://docs.endorlabs.com/api-reference/projectservice/getproject /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/projects/{uuid} Fetches comprehensive information about a project identified by a given UUID. # ListProjects Source: https://docs.endorlabs.com/api-reference/projectservice/listprojects /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/projects Lists all projects in a given namespace. # UpdateProject Source: https://docs.endorlabs.com/api-reference/projectservice/updateproject /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/projects Updates the specified project with the information in the request body. # GetProvisioningResult returns a provisioning result specified by its UUID. Source: https://docs.endorlabs.com/api-reference/provisioningresultservice/getprovisioningresult-returns-a-provisioning-result-specified-by-its-uuid /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/provisioning-results/{uuid} # ListProvisioningResults returns a list of provisioning results in a specified namespace. Source: https://docs.endorlabs.com/api-reference/provisioningresultservice/listprovisioningresults-returns-a-list-of-provisioning-results-in-a-specified-namespace /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/provisioning-results # CreateQueryMalware Source: https://docs.endorlabs.com/api-reference/querymalwareservice/createquerymalware /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/queries/malware Queries malware for specific values. Use this method to query malware for a specific package version. # CreateQuery Source: https://docs.endorlabs.com/api-reference/queryservice/createquery /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/queries Queries metrics for specific values. It returns back a list of metric UUIDs. The caller must call the List or Get metric to retrieve the individual metric values. # Queries packages which is lexicographically similar to a given package. Source: https://docs.endorlabs.com/api-reference/querysimilarpackagesservice/queries-packages-which-is-lexicographically-similar-to-a-given-package /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/queries/similar-packages # CreateQueryVulnerability Source: https://docs.endorlabs.com/api-reference/queryvulnerabilityservice/createqueryvulnerability /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/queries/vulnerabilities Queries vulnerabilities for specific values. Use this method to query vulnerabilities for a specific package version. # CreateRegistryIngestionCheckpoint Source: https://docs.endorlabs.com/api-reference/registryingestioncheckpointservice/createregistryingestioncheckpoint /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/registry-ingestion-checkpoints Creates a registry ingestion checkpoint. # DeleteRegistryIngestionCheckpoint Source: https://docs.endorlabs.com/api-reference/registryingestioncheckpointservice/deleteregistryingestioncheckpoint /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/registry-ingestion-checkpoints/{uuid} Deletes the registry ingestion checkpoint specified by the UUID. # GetRegistryIngestionCheckpoint Source: https://docs.endorlabs.com/api-reference/registryingestioncheckpointservice/getregistryingestioncheckpoint /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/registry-ingestion-checkpoints/{uuid} Fetches the registry ingestion checkpoint specified by the UUID. # ListRegistryIngestionCheckpoint Source: https://docs.endorlabs.com/api-reference/registryingestioncheckpointservice/listregistryingestioncheckpoint /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/registry-ingestion-checkpoints Lists registry ingestion checkpoints in a namespace. # UpdateRegistryIngestionCheckpoint Source: https://docs.endorlabs.com/api-reference/registryingestioncheckpointservice/updateregistryingestioncheckpoint /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/registry-ingestion-checkpoints Updates a registry ingestion checkpoint. # CreateRepository Source: https://docs.endorlabs.com/api-reference/repositoryservice/createrepository /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/repositories Creates a source control repository. The creation of the resource will be an upsert operation if the given spec.external_id and spec.platform_resource are already available. # DeleteRepository Source: https://docs.endorlabs.com/api-reference/repositoryservice/deleterepository /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/repositories/{uuid} Deletes a source control repository specified by its UUID. # GetRepository Source: https://docs.endorlabs.com/api-reference/repositoryservice/getrepository /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/repositories/{uuid} Fetches a source control repository identified by a given UUID. # ListRepositories Source: https://docs.endorlabs.com/api-reference/repositoryservice/listrepositories /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/repositories Lists the source control repositories in a given namespace. # UpdateRepository Source: https://docs.endorlabs.com/api-reference/repositoryservice/updaterepository /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/repositories Updates a source control repository with the information in the request body. # CreateRepositoryVersion Source: https://docs.endorlabs.com/api-reference/repositoryversionservice/createrepositoryversion /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/repository-versions Creates a repository version or updates a repository version if it already exists. # DeleteRepositoryVersion Source: https://docs.endorlabs.com/api-reference/repositoryversionservice/deleterepositoryversion /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/repository-versions/{uuid} Deletes a repository version specified by its UUID. # GetRepositoryVersion Source: https://docs.endorlabs.com/api-reference/repositoryversionservice/getrepositoryversion /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/repository-versions/{uuid} Fetches a repository version specified by its UUID. # ListRepositoryVersions Source: https://docs.endorlabs.com/api-reference/repositoryversionservice/listrepositoryversions /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/repository-versions Lists all repository versions in a given namespace. # UpdateRepositoryVersion Source: https://docs.endorlabs.com/api-reference/repositoryversionservice/updaterepositoryversion /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/repository-versions Updates a specified repository version with the information in the request body. # CreateRuleSetImport Source: https://docs.endorlabs.com/api-reference/rulesetimportservice/createrulesetimport /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/rule-set-imports Imports the given set of rules. # DeleteRuleSetImport Source: https://docs.endorlabs.com/api-reference/rulesetimportservice/deleterulesetimport /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/rule-set-imports/{uuid} Deletes an imported rule set object specified by its UUID. # GetRuleSetImport Source: https://docs.endorlabs.com/api-reference/rulesetimportservice/getrulesetimport /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/rule-set-imports/{uuid} Fetches an imported rule set object specified by its UUID. # ListRuleSetImports Source: https://docs.endorlabs.com/api-reference/rulesetimportservice/listrulesetimports /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/rule-set-imports Lists all imported rule set objects in a namespace. # UpdateRuleSetImport Source: https://docs.endorlabs.com/api-reference/rulesetimportservice/updaterulesetimport /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/rule-set-imports Updates an imported set of rules. # CreateSavedQuery Source: https://docs.endorlabs.com/api-reference/savedqueryservice/createsavedquery /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/saved-queries Creates a saved query. # DeleteSavedQuery Source: https://docs.endorlabs.com/api-reference/savedqueryservice/deletesavedquery /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/saved-queries/{uuid} Deletes the saved query specified by the UUID. # EvaluateSavedQuery Source: https://docs.endorlabs.com/api-reference/savedqueryservice/evaluatesavedquery /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/saved-queries/{uuid}/evaluate Evaluates the saved query, then returns the query and the result. # GetSavedQuery Source: https://docs.endorlabs.com/api-reference/savedqueryservice/getsavedquery /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/saved-queries/{uuid} Fetches the saved query identified by the UUID. # ListSavedQueries Source: https://docs.endorlabs.com/api-reference/savedqueryservice/listsavedqueries /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/saved-queries Lists all saved queries in a namespace. # UpdateSavedQuery Source: https://docs.endorlabs.com/api-reference/savedqueryservice/updatesavedquery /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/saved-queries Updates the saved queries. # CreateSBOMExport Source: https://docs.endorlabs.com/api-reference/sbomexportservice/createsbomexport /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/sbom-export Creates an SBOM export. # CreateSBOMImport Source: https://docs.endorlabs.com/api-reference/sbomimportservice/createsbomimport /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/sbom-imports Imports the given SBOM. # DeleteSBOMImport Source: https://docs.endorlabs.com/api-reference/sbomimportservice/deletesbomimport /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/sbom-imports/{uuid} Deletes an imported SBOM specified by its UUID. # GetSBOMImport Source: https://docs.endorlabs.com/api-reference/sbomimportservice/getsbomimport /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/sbom-imports/{uuid} Fetches an imported SBOM specified by its UUID. # ListSBOMImports Source: https://docs.endorlabs.com/api-reference/sbomimportservice/listsbomimports /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/sbom-imports Lists all imported SBOMS in a namespace. # UpdateSBOMImport Source: https://docs.endorlabs.com/api-reference/sbomimportservice/updatesbomimport /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/sbom-imports Updates an imported SBOM. # GetScanCreditUsage Source: https://docs.endorlabs.com/api-reference/scancreditusageservice/getscancreditusage /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scan-credit-usages/{uuid} Fetches a ScanCreditUsage record specified by its UUID. # ListScanCreditUsages Source: https://docs.endorlabs.com/api-reference/scancreditusageservice/listscancreditusages /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scan-credit-usages Lists ScanCreditUsage records visible in the namespace. # CreateScanLogRequest Source: https://docs.endorlabs.com/api-reference/scanlogrequestservice/createscanlogrequest /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/scan-log-requests Create a scan log request. # CreateScanProfile creates a toolchain profile. Source: https://docs.endorlabs.com/api-reference/scanprofileservice/createscanprofile-creates-a-toolchain-profile /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/scan-profiles # DeleteScanProfile deletes a toolchain profile specified by its UUID. Source: https://docs.endorlabs.com/api-reference/scanprofileservice/deletescanprofile-deletes-a-toolchain-profile-specified-by-its-uuid /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/scan-profiles/{uuid} # GetScanProfile returns a toolchain profile specified by its UUID. Source: https://docs.endorlabs.com/api-reference/scanprofileservice/getscanprofile-returns-a-toolchain-profile-specified-by-its-uuid /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scan-profiles/{uuid} # ListScanProfiles returns a list of toolchain profiles in a specified namespace. Source: https://docs.endorlabs.com/api-reference/scanprofileservice/listscanprofiles-returns-a-list-of-toolchain-profiles-in-a-specifiednamespace /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scan-profiles # UpdateScanProfile updates a specified Toolchain profile. Source: https://docs.endorlabs.com/api-reference/scanprofileservice/updatescanprofile-updates-a-specified-toolchain-profile /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/scan-profiles # CreateScanResult Source: https://docs.endorlabs.com/api-reference/scanresultservice/createscanresult /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/scan-results Create a scan result. # DeleteScanResult Source: https://docs.endorlabs.com/api-reference/scanresultservice/deletescanresult /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/scan-results/{uuid} Delete a specified scan result. # GetScanResult Source: https://docs.endorlabs.com/api-reference/scanresultservice/getscanresult /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scan-results/{uuid} Return a specified scan result. # ListScanResults Source: https://docs.endorlabs.com/api-reference/scanresultservice/listscanresults /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scan-results List scan results based on the specified list parameters. # UpdateScanResult Source: https://docs.endorlabs.com/api-reference/scanresultservice/updatescanresult /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/scan-results Update a specified scan result. # CreateScanWorkflowResult Source: https://docs.endorlabs.com/api-reference/scanworkflowresultservice/createscanworkflowresult /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/scan-workflow-results Creates a scan workflow result in a given namespace. # DeleteScanWorkflowResult Source: https://docs.endorlabs.com/api-reference/scanworkflowresultservice/deletescanworkflowresult /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/scan-workflow-results/{uuid} Deletes a scan workflow result specified by its UUID. # GetScanWorkflowResult Source: https://docs.endorlabs.com/api-reference/scanworkflowresultservice/getscanworkflowresult /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scan-workflow-results/{uuid} Fetches comprehensive information about a scan workflow result identified by a given UUID. # ListScanWorkflowResults Source: https://docs.endorlabs.com/api-reference/scanworkflowresultservice/listscanworkflowresults /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scan-workflow-results Lists all scan workflow results in a given namespace. # UpdateScanWorkflowResult Source: https://docs.endorlabs.com/api-reference/scanworkflowresultservice/updatescanworkflowresult /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/scan-workflow-results Updates the specified scan workflow result with the information in the request body. # CreateScanWorkflow Source: https://docs.endorlabs.com/api-reference/scanworkflowservice/createscanworkflow /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/scan-workflows Creates a scan workflow in a given namespace. # DeleteScanWorkflow Source: https://docs.endorlabs.com/api-reference/scanworkflowservice/deletescanworkflow /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/scan-workflows/{uuid} Deletes a scan workflow specified by its UUID. # GetScanWorkflow Source: https://docs.endorlabs.com/api-reference/scanworkflowservice/getscanworkflow /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scan-workflows/{uuid} Fetches comprehensive information about a scan workflow identified by a given UUID. # ListScanWorkflows Source: https://docs.endorlabs.com/api-reference/scanworkflowservice/listscanworkflows /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scan-workflows Lists all scan workflows in a given namespace. # UpdateScanWorkflow Source: https://docs.endorlabs.com/api-reference/scanworkflowservice/updatescanworkflow /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/scan-workflows Updates the specified scan workflow with the information in the request body. # CreateSCMCredential creates an SCM credential in the given namespace. Source: https://docs.endorlabs.com/api-reference/scmcredentialservice/createscmcredential-creates-an-scm-credential-in-the-given-namespace /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/scm-credentials # DeleteSCMCredential deletes the SCM credential specified by UUID. Source: https://docs.endorlabs.com/api-reference/scmcredentialservice/deletescmcredential-deletes-the-scm-credential-specified-by-uuid /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/scm-credentials/{uuid} # GetSCMCredential fetches the SCM credential identified by UUID. Source: https://docs.endorlabs.com/api-reference/scmcredentialservice/getscmcredential-fetches-the-scm-credential-identified-by-uuid /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scm-credentials/{uuid} # ListSCMCredentials lists all SCM credentials in the given namespace. Source: https://docs.endorlabs.com/api-reference/scmcredentialservice/listscmcredentials-lists-all-scm-credentials-in-the-given-namespace /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/scm-credentials # UpdateSCMCredential updates the SCM credential specified in the request. Source: https://docs.endorlabs.com/api-reference/scmcredentialservice/updatescmcredential-updates-the-scm-credential-specified-in-the-request /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/scm-credentials # CreateSecretRule Source: https://docs.endorlabs.com/api-reference/secretruleservice/createsecretrule /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/secret-rules Creates a secret rule. # DeleteSecretRule Source: https://docs.endorlabs.com/api-reference/secretruleservice/deletesecretrule /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/secret-rules/{uuid} Deletes the secret rule identified by the UUID. # GetSecretRule Source: https://docs.endorlabs.com/api-reference/secretruleservice/getsecretrule /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/secret-rules/{uuid} Fetches the secret rule identified by the UUID. # ListSecretRules Source: https://docs.endorlabs.com/api-reference/secretruleservice/listsecretrules /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/secret-rules Lists all secret rules in a namespace. # UpdateSecretRule Source: https://docs.endorlabs.com/api-reference/secretruleservice/updatesecretrule /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/secret-rules Updates a secret rule. # CreateSemgrepRule Source: https://docs.endorlabs.com/api-reference/semgrepruleservice/createsemgreprule /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/semgrep-rules Creates a Semgrep rule. # DeleteSemgrepRule Source: https://docs.endorlabs.com/api-reference/semgrepruleservice/deletesemgreprule /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/semgrep-rules/{uuid} Deletes the rule specified by the UUID. # GetSemgrepRule Source: https://docs.endorlabs.com/api-reference/semgrepruleservice/getsemgreprule /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/semgrep-rules/{uuid} Fetches a Semgrep rule identified by the UUID. # ListSemgrepRules Source: https://docs.endorlabs.com/api-reference/semgrepruleservice/listsemgreprules /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/semgrep-rules Lists all Semgrep rules in the namespace. # UpdateSemgrepRule Source: https://docs.endorlabs.com/api-reference/semgrepruleservice/updatesemgreprule /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/semgrep-rules Updates the Semgrep rule. # CreateSystemConfig Source: https://docs.endorlabs.com/api-reference/systemconfigservice/createsystemconfig /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/system-config Creates a system configuration object. # DeleteSystemConfig Source: https://docs.endorlabs.com/api-reference/systemconfigservice/deletesystemconfig /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/system-config/{uuid} Deletes the system configuration specified by the UUID. # GetSystemConfig Source: https://docs.endorlabs.com/api-reference/systemconfigservice/getsystemconfig /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/system-config/{uuid} Fetches the system configuration specified by the UUID. # ListSystemConfig Source: https://docs.endorlabs.com/api-reference/systemconfigservice/listsystemconfig /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/system-config Returns the system configuration as a list of length 1. # UpdateSystemConfig Source: https://docs.endorlabs.com/api-reference/systemconfigservice/updatesystemconfig /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/system-config Updates the system configuration. # CreateTenant Source: https://docs.endorlabs.com/api-reference/tenantservice/createtenant /api-reference/openapi.v3.json post /v1/tenants Creates a tenant. # DeleteTenant Source: https://docs.endorlabs.com/api-reference/tenantservice/deletetenant /api-reference/openapi.v3.json delete /v1/tenants/{uuid} Deletes a tenant specified by its UUID. # GetTenant Source: https://docs.endorlabs.com/api-reference/tenantservice/gettenant /api-reference/openapi.v3.json get /v1/tenants/{uuid} Fetches a tenant specified by its UUID. # ListTenants Source: https://docs.endorlabs.com/api-reference/tenantservice/listtenants /api-reference/openapi.v3.json get /v1/tenants Lists all tenants. # UpdateTenant Source: https://docs.endorlabs.com/api-reference/tenantservice/updatetenant /api-reference/openapi.v3.json patch /v1/tenants Updates a specified tenant. # GetVectorStore Source: https://docs.endorlabs.com/api-reference/vectorstoreservice/getvectorstore /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/vector-stores/{uuid} Fetches an VectorStore specified by its UUID. # ListVectorStores Source: https://docs.endorlabs.com/api-reference/vectorstoreservice/listvectorstores /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/vector-stores Lists all vector stores visible in a namespace. # CreateVersionUpgrade Source: https://docs.endorlabs.com/api-reference/versionupgradeservice/createversionupgrade /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/version-upgrades Creates a version upgrade. The creation of the resource will be an upsert if the given spec.external_id and spec.platform_resource were already created. # DeleteVersionUpgrade Source: https://docs.endorlabs.com/api-reference/versionupgradeservice/deleteversionupgrade /api-reference/openapi.v3.json delete /v1/namespaces/{tenant_meta.namespace}/version-upgrades/{uuid} Deletes a version upgrade specified by the UUID. # GetVersionUpgrade Source: https://docs.endorlabs.com/api-reference/versionupgradeservice/getversionupgrade /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/version-upgrades/{uuid} Fetches a version upgrade identified by the UUID. # ListVersionUpgrades Source: https://docs.endorlabs.com/api-reference/versionupgradeservice/listversionupgrades /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/version-upgrades Lists all version upgrades in the namespace. # UpdateVersionUpgrade Source: https://docs.endorlabs.com/api-reference/versionupgradeservice/updateversionupgrade /api-reference/openapi.v3.json patch /v1/namespaces/{object.tenant_meta.namespace}/version-upgrades Updates a version upgrade. # Post v1namespaces vex export Source: https://docs.endorlabs.com/api-reference/vexexportservice/post-v1namespaces-vex-export /api-reference/openapi.v3.json post /v1/namespaces/{tenant_meta.namespace}/vex-export # GetVulnerability Source: https://docs.endorlabs.com/api-reference/vulnerabilityservice/getvulnerability /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/vulnerabilities/{uuid} Fetches a vulnerability identified by the UUID. # ListVulnerabilities Source: https://docs.endorlabs.com/api-reference/vulnerabilityservice/listvulnerabilities /api-reference/openapi.v3.json get /v1/namespaces/{tenant_meta.namespace}/vulnerabilities List all vulnerabilities in the namespace. # Best Practices: Build tools use cases Source: https://docs.endorlabs.com/best-practices/build-tools-use-case/index Explore common build tool scenarios and strategies to configure scan profiles for accurate and reliable scans Endor Labs relies on build tools such as compilers, runtimes, and package managers to scan applications accurately. These tools are essential for reproducing your project’s build environment during a scan. This is especially important for languages like Python, Java, or .NET, where lock files are less common and exact tool versions help ensure consistency. By specifying build tools in your scan profile, you can avoid issues like incorrect language detection, broken dependencies, or missing findings. Scans may fail if the toolchain is incorrect or required build tools are missing. A well-configured scan profile aligns the environment with your project and ensures accurate results. You can configure toolchains and build tools in scan profiles in multiple ways: * [Configure scan profile through Endor Labs user interface](/scan/scan-profiles/configure-scanprofile-ui) * [Configure scan profile through `scanprofile.yaml`](/scan/scan-profiles/configure-scanprofile-yaml) * [Configure scan profile through Endor Labs API](/scan/scan-profiles/configure-scanprofile-api) ## Auto detection of toolchains Auto detection takes place when you have not configured a scan profile or build tool for a project. The process identifies the toolchain versions required by the project and compares them with the versions that Endor Labs supports. See the [toolchain support matrix](/scan/scan-profiles/build-tools#toolchain-support-matrix) to learn more about supported versions and [auto detection](/scan/scan-profiles/auto-detect-toolchains) to learn about the complete process. Use the `--install-build-tools` flag to enable auto detection in endorctl scans. ## Build tool use case scenarios Understanding build tools use cases help you improve scan accuracy and streamline your scanning process. Here are some common use cases for build tools that show how you can customize scan profiles to better match your project’s needs. ### Configure tool versions for multi-language projects You can configure language specific tool versions in a single scan profile based on OS and architecture. For example, to scan a multi-language repository with `Python`, `Golang`, and `Node.js`, set `Python 3.9.19`, `Golang 1.22.7`, and `Node.js 20.10.0`. During the scan, Endor Labs applies the configured toolchain version for each language. This ensures accurate builds, better dependency resolution, and improved findings. Multiple language repository ### Toolchain versions across different architectures In a multi-architecture environment, you can configure toolchains for operating system and architecture combination to ensure scans align with system specific setups. For example, a Linux AMD64 machine with `Python 3.8.0` installed but `Python 3.8.19` specified in the toolchain configuration will use version `3.8.19` during scans. A macOS AMD64 machine with `Python 3.10.14` installed but `Python 3.7.0` configured will use the system’s `Python 3.10.14`. Meanwhile, a macOS ARM64 machine without any version of `Python` installed and no toolchain configured will use `Python 3.12.4`, the default version supported by Endor Labs. Multiple architecture ### Configure custom toolchains for unsupported versions Set up a custom toolchain version when your project depends on a specific version not provided by Endor Labs. This gives you precise control over the scanning environment and helps avoid issues caused by version mismatches. For example, the default list supports Java up to `17`. If your project needs `23.0.2` and you haven't configured a toolchain, the scan fails. In such cases, create a custom build toolchain for `Java 23.0.2` in your scan profile and link it to your project. When you re-run the scan, Endor Labs uses the configured `23.0.2` version and gives reliable results. This configuration works only in the namespace where you created the build tool. See [configure custom version for the toolchain](/scan/scan-profiles/configure-scanprofile-ui#configure-a-custom-version-for-a-tool) to learn how to configure custom version for a toolchain. Custom toolchain version for Java which is not provided by Endor Labs ### Custom and default toolchain version strategy Endor Labs selects the toolchain version for each language based on your scan profile. When you configure toolchain versions for some languages and leave others unspecified, the scan uses your specified versions and defaults to the Endor Labs toolchain matrix for the remaining languages. For example, your scan profile specifies `Yarn 3.8.7` and `pnpm 8.10.2` but omits a `Node.js` version. Endor Labs uses the configured `Yarn` and `pnpm` versions and selects `Node.js 20.10.0` from the default list. This approach ensures your project builds successfully without requiring extra configuration. Default and configured ### Reuse build tool configurations across multiple projects Multiple projects often require specific custom toolchain versions, which you can configure in your scan profile. For example, `Project A` needs `Python 3.13.0` and `Go 1.24.6` and `Project B` requires the same `Python` and `Go` versions, and an additional `Java 22.0.2`. Configuring each toolchain separately for these two project can be time-consuming. You can configure these build tools and name them `3.13.0` and `1.24.6` in your namespace. See [configure build tools](/scan/scan-profiles/configure-scanprofile-ui#configure-build-tools) for setup instructions. Build tools use case 1 * For Project A's scan profile, add these reusable build tools in its scan profile. Build tools use case 3 * For Project B's scan profile, add the same reusable build tools and the additional Java toolchain. Build tools use case 2 This approach reduces duplication, saves time, and ensures consistent toolchain use across projects. These reusable build tool configurations are namespace specific, so only projects within your namespace can access them. Use clear, unique, and consistent naming for build tool and scan profiles to improve visibility and promote reuse. For example `frontend-node16`, `backend-java17`, `shared-go120`. # Best Practices: GitHub Security Campaign Source: https://docs.endorlabs.com/best-practices/github-security-campaign/index Learn how to plan, execute, and monitor GitHub security campaigns using Endor Labs and GitHub Advanced Security. A GitHub Security Campaign is a time-bound effort to find, fix, and prevent vulnerabilities across multiple repositories. Endor Labs and GitHub Advanced Security (GHAS) turn findings into coordinated fixes that keep developers working in GitHub. This approach works well when projects share vulnerable dependencies or when your organization faces compliance deadlines. Endor Labs generates vulnerability findings in SARIF format. Upload the SARIF output to GitHub Advanced Security manually or with a configured GHAS exporter. After import, these findings become actionable alerts that help developers triage, fix, and track vulnerabilities without leaving their familiar environment. The security campaign allows organizations to: * Target a specific class of vulnerabilities, for example `Log4j`, or `CVE-2024-xyz`. * Drive dependency upgrades and security fixes across all affected repositories. * Address secrets detection and SAST findings alongside for comprehensive security remediation. * Enforce consistent remediation timelines and accountability across teams. * Monitor reduction in overall security debt using both GitHub's campaign dashboard and Endor Labs analytics. Ensure you have deployed [Endor Labs](/setup-deployment) and enabled [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) before creating a security campaign. ## Create and manage a security campaign Use GitHub Security Campaigns to coordinate large-scale remediation by importing Endor Labs findings. 1. Run a scan with Endor Labs to generate vulnerability findings in SARIF format and upload them to GitHub Advanced Security. See [SARIF output format](/scan/sca/scanning-strategies#understand-sarif-files) for detailed information on generating, customizing, and uploading SARIF files. **Automatic SARIF upload** Configure Endor Labs GitHub App (Pro) with a GHAS SARIF exporter to automatically upload findings to GitHub after each scan. See [Export findings to GitHub Advanced Security](/integrations/data-exporters/export-to-ghas) for setup instructions. 2. In GitHub, navigate to **Security > Campaigns > New Campaign** to define your campaign parameters. Refer to [security campaign guide](https://docs.github.com/en/enterprise-cloud@latest/code-security/securing-your-organization/fixing-security-alerts-at-scale/creating-managing-security-campaigns) for more information on GitHub's campaign features and configuration options. 3. Define the scope of your campaign. * **Organization-wide**: Apply the campaign across all repositories in your organization. * **Selected repositories**: Target specific repositories affected by the vulnerability class. * **Teams or projects**: Scope by team ownership or project grouping. 4. Specify a clear focus area of the campaign that aligns with your security requirements. For example, remediating Log4j vulnerabilities across Java projects, or upgrading vulnerable npm packages to secure versions. 5. Define campaign objectives with clear remediation timelines. For example, close 80% of critical dependency vulnerabilities within 30 days, or fully remediate exposed secrets within 10 days. 6. Monitor campaign metrics in GitHub, including percentage of vulnerabilities remediated, active versus resolved alerts, and repository-level completion. ## Best practices Security campaigns help you fix alerts at scale and build developer security knowledge. Follow these practices for successful campaigns. ### Plan and prioritize alerts strategically Select a related group of security alerts for remediation rather than attempting to fix all alerts at once. For organizations building secure coding knowledge, prioritize alerts that can serve as learning opportunities. Use Endor Labs' reachability analysis and severity scoring to identify high-impact vulnerabilities. * Focus on **reachable** vulnerabilities where the vulnerable code is actually used in execution paths. * Filter by **exploitability score**, **CVE severity**, or **policy violation type**. * Use **Endor Labs Dependency Graph** to visualize transitive relationships and focus on the most impactful fixes. You can tag repositories with metadata such as `critical`, `frontend`, or `backend` in Endor Labs and scope your campaign accordingly. Exclude inactive or archived repositories to focus efforts where they matter most. ### Provide educational resources Include links to relevant educational materials in the campaign description to help developers understand and remediate vulnerabilities effectively, such as OWASP references, secure secrets management guides, or internal upgrade instructions. ### Enable AI assistance for faster remediation Leverage AI-powered tools to accelerate remediation while maintaining code quality: * Use **GitHub Copilot Autofix** to suggest fixes for code scanning alerts automatically, reducing manual effort. * Make **GitHub Copilot Chat** available for developers to ask questions about vulnerabilities, testing, and secure coding best practices. * Enable **Endor Labs automated remediation PRs** to create pull requests with updated dependency versions, vulnerability references (CVE IDs, severity, reachability), and compatibility checks. ### Assign and support campaign managers Campaign managers play a critical role in maintaining momentum and ensuring developers have the support they need to succeed. Campaign managers should: * Review PRs, provide guidance, and maintain consistent communication. * Provide a contact link for questions and collaboration. * Monitor progress and provide support where needed to ensure sustained engagement. * Help resolve complex or unclear fixes through open communication with developers. ### Define realistic deadlines Set timelines according to issue complexity and remediation scope. Simple dependency upgrades require minimal validation, whereas compatibility or architectural fixes need extended testing and integration checks. Align campaigns with sprint cycles or release milestones. Iterative, focused campaigns lead to more predictable outcomes and better code quality. ### Track progress and engagement Monitor campaign performance through GitHub dashboards. Track remediation percentage, active versus resolved alerts, repository-level progress, and time-to-fix metrics. Use GitHub Issues for task tracking and developer communication. Use GitHub labels such as `security-campaign-q4` or `log4j-remediation` on issues and pull requests to enable easy filtering and audit tracking across repositories. ### Log4j vulnerability remediation example **Scenario:** A critical Log4j vulnerability affects multiple Java microservices across the organization. **Campaign execution:** 1. Export a SARIF file containing all dependency vulnerabilities from Endor Labs. 2. Upload the SARIF file to GitHub to populate alerts across affected repositories. 3. Create a security campaign titled “Fix outdated Log4j dependencies across all repos”. 4. Assign the campaign to the Java development team with a 30-day remediation deadline. 5. Developers fix vulnerabilities directly in GitHub by updating affected dependencies. 6. The security team monitors campaign progress in GitHub until developers resolve 85% of alerts, then closes the campaign. **Outcome:** The organization remediates 85% of Log4j-related vulnerabilities within 30 days, improving dependency security posture and reducing exposure to known CVEs. ## FAQs Yes. Security campaigns work with both public and private repositories. For private repositories, turn on GitHub Advanced Security and grant the Endor Labs GitHub App the permissions it needs. GitHub's campaign filters and Endor Labs' vulnerability data determine which alerts appear in a campaign. Use Endor Labs' reachability analysis to prioritize alerts where vulnerable code is actively used in execution paths. GitHub permits a maximum of 10 active campaigns, each with up to 1,000 alerts. You can prioritise active repositories, target specific vulnerability types, close completed campaigns swiftly, and run campaigns sequentially or split them into focused initiatives Yes. You can run multiple campaign types simultaneously, such as dependency remediation, secrets rotation, and license compliance. Each campaign can target different repositories, teams, or vulnerability classes. GitHub Security Campaigns integrate with GitHub Issues, GitHub Actions, Slack, Jira, and Endor Labs. You can export Campaign data to business intelligence tools and internal reporting dashboards # Best Practices Source: https://docs.endorlabs.com/best-practices/index Learn how to integrate Endor Labs most effectively into your organization's workflows. These resources help you get the most from Endor Labs. Whether you’re just getting started or improving an existing setup, you’ll find strategies and tips for common use cases. Strategies for scanning different branches and managing baseline comparisons. Effectively scope your scans with inclusion and exclusion patterns. Manage API keys, check for expiring keys, and automate key rotation. Use Jira efficiently with Endor Labs to manage security findings. Plan, execute, and monitor GitHub security campaigns with Endor Labs and GHAS. Configure scan profiles for accurate and reliable scans with common build tool scenarios. Implement project filters to search, prioritize, and manage projects across your organization. Scan different branches, set up baselines, and integrate PR scans into your workflow. Diagnose and resolve common issues with Endor Labs scans. # Best Practices: API key management Source: https://docs.endorlabs.com/best-practices/manage-api-keys/index Learn how to manage API keys, check for expiring keys, and automate key rotation. You can use API keys to engage with Endor Labs services programmatically to enable any automation or integration with other systems in your environment. See [Manage API keys](/platform-administration/api-keys) for more information on how to create and delete API keys. Ensure that you rotate API keys regularly to limit how long a stolen API key stays valid. Instead of using API keys, you can use keyless authentication to authenticate with Endor Labs services. See [Keyless authentication](/setup-deployment/ci-cd/keyless-authentication) for more information. Using keyless authentication eliminates the need to manage API keys and reduces the risk of API key compromise. You can use the Endor Labs API to programmatically create scripts to manage API keys. ## Check for expiring API keys API key expiry can cause interruptions in your workflows. It is a good practice to check for expiring API keys so that you can rotate them before they expire. You can use the following script (`key-expiry.sh`) to check for expiring API keys. By default, the script checks for API keys that expire in the next day in the currently configured namespace. You can pass the `-d` flag with a number to check for API keys that expire in the next `n` days. You can also pass a namespace with the `-n` flag followed by the namespace name to check for expiring API keys in a specific namespace. The script uses [`jq`](https://jqlang.org/) to parse the json response and generate a formatted output. If you do not have `jq` installed, the script provides a json output. ```shell expandable theme={null} #!/bin/bash # Default values. You can update the values here or pass the values as flags to the script. DAYS=1 NAMESPACE="" NAMESPACE_FLAG="" while getopts "n:d:" opt; do case $opt in n) NAMESPACE=$OPTARG NAMESPACE_FLAG="-n $NAMESPACE" ;; d) DAYS=$OPTARG ;; \?) echo "Invalid option: -$OPTARG" >&2 echo "Usage: $0 [-n namespace] [-d days]" >&2 exit 1 ;; :) echo "Option -$OPTARG requires an argument." >&2 echo "Usage: $0 [-n namespace] [-d days]" >&2 exit 1 ;; esac done TODAY=$(date +"%Y-%m-%d") # Detect OS type and use appropriate date command if [[ "$OSTYPE" == "darwin"* ]]; then # macOS PLUS_DAYS=$(date -v+${DAYS}d +"%Y-%m-%d") else # Other Unix systems PLUS_DAYS=$(date -d "+${DAYS} days" +"%Y-%m-%d") fi if [ -z "$NAMESPACE" ]; then echo "Searching for API keys expiring between $TODAY and $PLUS_DAYS ($DAYS days)" else echo "Searching for API keys in namespace '$NAMESPACE' expiring between $TODAY and $PLUS_DAYS ($DAYS days)" fi # Check if jq is available if command -v jq &> /dev/null; then # jq is available, use it for formatted output RESULT=$(endorctl api list $NAMESPACE_FLAG -r APIKey \ --filter="spec.expiration_time >= date($TODAY) AND spec.expiration_time <= date($PLUS_DAYS)" \ --field-mask "meta.name,spec.expiration_time,meta.created_by,spec.issuing_user.spec.email" -o json) if echo "$RESULT" | jq -e '.list.objects | length > 0' &>/dev/null; then echo "$RESULT" | jq '.list.objects[] | {name: .meta.name, expiration: .spec.expiration_time, user: .meta.created_by, email: .spec.issuing_user.spec.email}' else echo "No API keys found expiring in the specified date range." fi else # jq is not available, use the regular output echo "Note: Install jq for better formatted output" endorctl api list $NAMESPACE_FLAG -r APIKey \ --filter="spec.expiration_time >= date($TODAY) AND spec.expiration_time <= date($PLUS_DAYS)" \ --field-mask "meta.name,spec.expiration_time" fi ``` The script returns the API keys that are expiring in the specified days. The output contains the key name, expiry date, and the information about the user that created the key. You can inform the user that the API key is expiring in the specified days and ask them to rotate the API key. See [Create API keys](/platform-administration/api-keys#create-an-api-key) for more information on how to create API keys. ### Create a cron job to check for expiring API keys You can also create a cron job to run the script at a regular interval and fetch the details of the expiring API keys. The following example shows a cron job script, `check_key_expiry_cron.sh`, that wraps the `key-expiry.sh` script, and sends an email to the specified email address if there are expiring API keys. Configure the script with the script path, number of days to check, email address for the report, and namespace. ```shell theme={null} #!/bin/bash # Configuration - Customize these values according to your needs SCRIPT_PATH="/path/to/key-expiry.sh" DAYS=1 # Days to check for expiring API keys EMAIL="your-email@example.com" NAMESPACE="" # Namespace to check for expiring API keys OUTPUT=$($SCRIPT_PATH -d $DAYS $([[ -n $NAMESPACE ]] && echo "-n $NAMESPACE")) if [ $(echo "$OUTPUT" | wc -l) -gt 1 ]; then echo "$OUTPUT" | mail -s "API Keys Expiring in the Next $DAYS Days" $EMAIL fi ``` Run the following command to create a cron job that runs the script at 8 AM every day if you keep the script in your home directory. ```shell theme={null} 0 8 * * * $HOME/check_key_expiry_cron.sh ``` ## Check for API keys with long expiry API keys with long expiry can be a security risk. The Endor Labs Create API key endpoint allows you to create API keys with expiry time of over 365 days. Such long expiry times may not be necessary and incompatible with your security policies. You can use the following script (`check_long_expiry_keys.sh`) to check for API keys with long expiry. The script checks for API keys with expiry dates longer than 365 days by default on the currently configured namespace. You can pass the `-d` flag with a number to check for API keys with expiry days according to the number you pass. You can also choose to pass an Endor Labs namespace to search for long expiry API keys in a specific namespace with the `-n` flag followed by the namespace name. The script uses [`jq`](https://jqlang.org/) to parse the json response. ```shell expandable theme={null} #!/bin/bash # Default values DAYS=365 NAMESPACE="" NAMESPACE_FLAG="" # Parse command line options while getopts "n:d:" opt; do case $opt in n) NAMESPACE=$OPTARG NAMESPACE_FLAG="-n $NAMESPACE" ;; d) DAYS=$OPTARG ;; \?) echo "Invalid option: -$OPTARG" >&2 echo "Usage: $0 [-n namespace] [-d days]" >&2 exit 1 ;; :) echo "Option -$OPTARG requires an argument." >&2 echo "Usage: $0 [-n namespace] [-d days]" >&2 exit 1 ;; esac done # Calculate today's date in YYYY-MM-DD format TODAY=$(date +"%Y-%m-%d") # Detect OS type and use appropriate date command for calculating the future date if [[ "$OSTYPE" == "darwin"* ]]; then # macOS PLUS_DAYS=$(date -v+${DAYS}d +"%Y-%m-%d") else # Linux PLUS_DAYS=$(date -d "+${DAYS} days" +"%Y-%m-%d") fi # Print info about the search if [ -z "$NAMESPACE" ]; then echo "Searching for API keys with expiration dates longer than $DAYS days from today ($TODAY to $PLUS_DAYS)" else echo "Searching for API keys in namespace '$NAMESPACE' with expiration dates longer than $DAYS days from today ($TODAY to $PLUS_DAYS)" fi # Check if jq is available if command -v jq &> /dev/null; then # jq is available, use it for formatted output RESULT=$(endorctl api list $NAMESPACE_FLAG -r APIKey \ --filter="spec.expiration_time > date($PLUS_DAYS)" \ --field-mask "meta.name,spec.expiration_time,meta.created_by,spec.issuing_user.spec.email" -o json) # Check if list.objects exists and is not empty if echo "$RESULT" | jq -e '.list.objects | length > 0' &>/dev/null; then echo "$RESULT" | jq '.list.objects[] | {name: .meta.name, expiration: .spec.expiration_time, user: .meta.created_by, email: .spec.issuing_user.spec.email}' else echo "No API keys found with expiration dates longer than $DAYS days." fi else # jq is not available, use the regular output echo "Note: Install jq for better formatted output" endorctl api list $NAMESPACE_FLAG -r APIKey \ --filter="spec.expiration_time > date($PLUS_DAYS)" \ --field-mask "meta.name,spec.expiration_time" fi ``` The script returns the API keys with expiry dates longer than the number of days, expiry date, and the information about the user that created the key. ## Clean up expired API keys You should regularly check for and delete expired API keys. Keeping only active and necessary API keys can improve system performance by reducing the volume of data Endor Labs processes during authentication checks. Regular cleanup makes it easier to manage and monitor active keys, allowing for better oversight of API access and usage patterns. You can use the Endor Labs API to check for expired API keys and delete them. The following script (`delete-expired-keys.sh`) checks for expired API keys and presents the options to delete them. You can choose to pass an Endor Labs namespace to search for expired API keys in a specific namespace. If you do not pass a namespace, the script checks for expired API keys in the currently configured namespace. The script uses [`jq`](https://jqlang.org/) to parse the json response. ```shell expandable theme={null} #!/bin/bash # Add a namespace to search for expired API keys in a specific namespace NAMESPACE="" NAMESPACE_FLAG="" while getopts "n:" opt; do case $opt in n) NAMESPACE=$OPTARG NAMESPACE_FLAG="-n $NAMESPACE" ;; \?) echo "Invalid option: -$OPTARG" >&2 echo "Usage: $0 [-n namespace]" >&2 exit 1 ;; :) echo "Option -$OPTARG requires an argument." >&2 echo "Usage: $0 [-n namespace]" >&2 exit 1 ;; esac done TODAY=$(date +"%Y-%m-%d") if [ -z "$NAMESPACE" ]; then echo "Searching for expired API keys (expiration date before $TODAY)" else echo "Searching for expired API keys in namespace '$NAMESPACE' (expiration date before $TODAY)" fi check_jq() { if ! command -v jq &> /dev/null; then echo "Error: This script requires jq to be installed." echo "Please install jq and try again." exit 1 fi } check_jq # Get all expired API keys RESULT=$(endorctl api list $NAMESPACE_FLAG -r APIKey \ --filter="spec.expiration_time < date($TODAY)" \ --field-mask "meta.name,spec.expiration_time,uuid" -o json) # Check if there are any expired keys if ! echo "$RESULT" | jq -e '.list.objects | length > 0' &>/dev/null; then echo "No expired API keys found." exit 0 fi KEY_COUNT=$(echo "$RESULT" | jq '.list.objects | length') echo "Found $KEY_COUNT expired API key(s)." echo -e "\nExpired API Keys:" echo "====================" echo "$RESULT" | jq -r '.list.objects[] | "ID: \(.uuid)\nName: \(.meta.name)\nExpired: \(.spec.expiration_time)\n"' echo -e "\nWould you like to delete these expired API keys?" echo "1) Delete all expired keys" echo "2) Select keys to delete individually" echo "3) Exit without deleting" read -p "Choose an option (1-3): " CHOICE case $CHOICE in 1) echo -e "\nDeleting all expired API keys..." for UUID in $(echo "$RESULT" | jq -r '.list.objects[].uuid'); do echo -n "Deleting key with UUID $UUID... " if endorctl api delete $NAMESPACE_FLAG -r APIKey --uuid=$UUID &> /dev/null; then echo "Success" else echo "Failed" fi done ;; 2) echo -e "\nSelecting keys to delete individually:" for UUID in $(echo "$RESULT" | jq -r '.list.objects[].uuid'); do NAME=$(echo "$RESULT" | jq -r ".list.objects[] | select(.uuid == \"$UUID\") | .meta.name") EXPIRY=$(echo "$RESULT" | jq -r ".list.objects[] | select(.uuid == \"$UUID\") | .spec.expiration_time") echo -e "\nID: $UUID" echo "Name: $NAME" echo "Expired: $EXPIRY" read -p "Delete this key? (y/n): " DELETE if [[ $DELETE == "y" || $DELETE == "Y" ]]; then echo -n "Deleting... " if endorctl api delete $NAMESPACE_FLAG -r APIKey --uuid=$UUID &> /dev/null; then echo "Success" else echo "Failed" fi else echo "Skipped" fi done ;; 3) echo "Exiting without deleting any keys." ;; *) echo "Invalid option. Exiting without deleting any keys." ;; esac echo -e "\nOperation completed." ``` ### Create a cron job to check for expired API keys You can also create a cron job to run the script at a regular interval. The following example shows a cron job script, `check_expired_keys_cron.sh`, that wraps the `delete-expired-keys.sh` script. Configure the script with the operation mode (delete or report), script path, email address, and namespace. ```shell expandable theme={null} #!/bin/bash # Configuration - Customize these values according to you need SCRIPT_PATH="/path/to/delete-expired-keys.sh" EMAIL="your-email@example.com" NAMESPACE="" # Set the required namespace or leave empty to check API keys in the currently configured namespace OPERATION="REPORT" # Set that value as "DELETE" to delete expired API keys # Create a temporary file for the report TEMP_REPORT=$(mktemp) # Function to send email with the report send_email() { local subject="$1" cat $TEMP_REPORT | mail -s "$subject" $EMAIL echo "Email sent with expired API keys report." } if [ "$OPERATION" = "REPORT" ]; then if [ -z "$NAMESPACE" ]; then echo "3" | $SCRIPT_PATH > $TEMP_REPORT 2>&1 else echo "3" | $SCRIPT_PATH -n $NAMESPACE > $TEMP_REPORT 2>&1 fi if grep -q "Found [1-9][0-9]* expired API key" $TEMP_REPORT; then send_email "Expired API Keys Found - Action Required" else echo "No expired API keys found." fi elif [ "$OPERATION" = "DELETE" ]; then if [ -z "$NAMESPACE" ]; then echo "1" | $SCRIPT_PATH > $TEMP_REPORT 2>&1 else echo "1" | $SCRIPT_PATH -n $NAMESPACE > $TEMP_REPORT 2>&1 fi if grep -q "Found [1-9][0-9]* expired API key" $TEMP_REPORT; then send_email "Expired API Keys Deleted - Action Taken" else echo "No expired API keys found." fi else echo "Invalid OPERATION value: $OPERATION. Must be 'REPORT' or 'DELETE'." > $TEMP_REPORT send_email "ERROR: Invalid Expired API Keys Operation" fi rm $TEMP_REPORT ``` You can use the following command to create a cron job that runs the script at 8 AM every day. ```shell theme={null} 0 8 * * * $HOME/check_expired_keys_cron.sh ``` # Best Practices: Branches and workflows Source: https://docs.endorlabs.com/best-practices/operational-best-practices/index Learn how to scan different branches, set up baseline branches, and integrate PR scans into your development workflow. Explore how to effectively use Endor Labs to scan different branches within your organization's software development workflows. Properly managing branches and integrating robust scanning processes is crucial for maintaining code quality, security, and consistency across your development pipeline. This guide shows you how to set up Endor Labs to scan and monitor your branches and catch issues early. A typical Git Flow may include the following types of branches: * `main` * `develop` * `release` * `feature` * `hotfix` The two primary branches in Git Flow are `main` and `develop`. The `main` or the `develop` branch stores the official release history and often serves as the integration branch for features. The `feature`, `release`, and `hotfix` branches can serve as supporting branches with different intended purposes. ## Baseline branch A baseline branch is any branch that falls into one of the following categories: * A branch used to maintain release history or as a single source of truth * A branch used for managing releases * A branch serving as a source of integration for features and bug fixes In the Git flow model, `main`, `release`, and `develop` can serve as the baseline branch. The `main` branch is typically the primary branch and is often chosen as the default branch in a Git repository. It serves as the central integration point and holds the most stable version of the codebase with the latest approved changes. This is why we recommend using `main` not only as the baseline branch but also as the default branch for repositories. Endor Labs uses metrics from the default branch as the primary context for displaying statistics and metrics on the dashboards. ### Why should you scan the baseline branches Scan the baseline branches to: * **Establish a security and quality baseline**: Scanning the baseline branch helps establish a reference point for the security and quality standards of your code, allowing you to identify any deviations or new vulnerabilities in subsequent branches. * **Detect inherited issues**: By scanning the baseline branch, you can catch existing issues that other branches might inherit, and address those problems before they proliferate throughout your development workflow. It will help you understand the current state of security. * **Ensure consistency across development**: Regularly scanning the baseline branch ensures that all branches derived from it start from a consistent and secure foundation, reducing the risk of introducing errors or vulnerabilities to your project. ### How to scan the baseline branch Set up a trigger to initiate a scan whenever you merge changes into the baseline branch, or schedule daily scans to ensure continuous monitoring. Perform a standard scan with additional configuration to enhance the process. By default, Endor Labs uses the first scanned branch as the default branch. Override this with the `--as-default-branch` argument to designate a baseline branch as the default during future scans. This ensures Endor Labs uses the correct context for dashboard statistics. For more information, see the [GitHub Actions templates](https://github.com/Endor-Solutions-Architecture/CI-CD-Examples/tree/main/github_actions_workflows) you can use in your CI pipelines. The repository also includes examples of other CI tools. ## Feature or hotfix branch A feature or hotfix branch is a specialized branch in a version control system used to develop and integrate new features and bug fixes into the existing codebase. Teams typically introduce changes to the code through pull requests. ### Why should you scan the feature branches through your pull requests * **Prevent security vulnerabilities**: Monitor pull requests to prevent the introduction of new vulnerable dependencies with known vulnerabilities, helping to maintain a secure codebase. * **Enforce security policies**: You can begin enforcing security policies to safeguard your codebase and ensure compliance with established best practices. * **Perform incremental scans**: Once you assess existing vulnerabilities in your baseline branch, you can [perform incremental scans](/scan/pr-scans#perform-incremental-pr-scan) to optimize efficiency on your pull requests. Focus on these incremental scans to identify new vulnerabilities, and skip scanning pull requests if a package and its dependencies remain unchanged. ### How to scan the feature branches through your pull requests Trigger PR scans on pull requests to the baseline branch with the following arguments: * `--pr` (For GitHub Actions use `pr: true`) * `--pr-baseline: {baseline_branch}` (For GitHub Actions use `pr_baseline: true`) * `--pr-incremental` (For GitHub Actions use `additional_args: --pr-incremental`) For more information, see the [templates](https://github.com/Endor-Solutions-Architecture/CI-CD-Examples/tree/main/github_actions_workflows) that you can use in your CI pipelines. For more details on how to perform endorctl scans and scan parameters, see [Scan with Endor Labs](/scan/sca) and [endorctl CLI](/developers-api/cli). # Best Practices: Scoping scans Source: https://docs.endorlabs.com/best-practices/scoping-scans/index Learn how to effectively scope your scans with Endor Labs inclusion and exclusion patterns. Exclude and include filters help your team to focus their attention on the open source packages that matter most and to improve scan performance. Use inclusion patterns when you have many packages that you want to scan separately and exclusion patterns when you want to filter out packages that are not important to you. You can include or exclude packages using the following standard patterns: 1. Include or exclude specific packages. 2. Include or exclude specific directories. 3. Include or exclude with a Glob style expressions. 4. Use include and exclude patterns together to exclude specific directories such as a test directory from a scan. 5. Use multiple include and exclude patterns together to exclude or include specific directories or file paths. ## Scoping scans with endorctl To include or exclude a package based on its file name when you scan with endorctl. ```bash theme={null} endorctl scan --include-path="path/to/your/manifest/file/package.json" ``` ```bash theme={null} endorctl scan --exclude-path="path/to/your/manifest/file/package.json" ``` To include or exclude a package based on its directory ```bash theme={null} endorctl scan --include-path="directory/path/**" ``` ```bash theme={null} endorctl scan --include-path="src/java/**" ``` ```bash theme={null} endorctl scan --exclude-path="path/to/your/directory/**" ``` ```bash theme={null} endorctl scan --exclude-path="src/ruby/**" ``` ## Examples of scoping scans The following examples show how you can use scoping scans. ### Exclude an entire directory tree Use `--exclude-path="src/java/**"` to exclude all files under `src/java`, including all subdirectories. ```bash theme={null} endorctl scan --exclude-path="src/java/**" ``` ### Exclude only top-level files in a directory (not subdirectories) Use `--exclude-path="src/python/*"` to exclude only the files directly under `src/python`, leaving any subdirectories untouched. ```bash theme={null} endorctl scan --exclude-path="src/python/*" ``` `*` matches files in the current directory only. `**` matches files in the current directory and nested subdirectories. ### Scan a directory while excluding its test folder Use `--include-path` and `--exclude-path` together to scan a specific directory while skipping test code. ```bash theme={null} endorctl scan --include-path="src/go/**" --exclude-path="src/go/test/**" ``` ### Scan multiple languages in the same repository Use multiple `--include-path` flags to scan several tech stacks at once, useful in polyglot monorepos. ```bash theme={null} endorctl scan --quick-scan \ --include-path="services/java/**" \ --include-path="services/python/**" \ --include-path="services/dotnet/**" ``` ### Include a directory while excluding specific build-tool directories Use multiple `--exclude-path` flags to skip dependency or build-tool directories you don't want analyzed. ```bash theme={null} endorctl scan \ --include-path="src/ruby/**" \ --exclude-path="src/ruby/vendor/**" \ --exclude-path="src/ruby/tmp/**" ``` ### Exclude a single manifest file Exclude a specific file rather than a whole directory — for example, a package manifest in a legacy module you don't want scanned. ```bash theme={null} endorctl scan --exclude-path="legacy/deprecated/package.json" ``` ### Exclude multiple specific files Use multiple `--exclude-path` flags to target specific manifest files in different locations. ```bash theme={null} endorctl scan --exclude-path="src/auth/package.json" --exclude-path="src/legacy/package.json" ``` ### Exclude files by extension across the repository Use a `**` glob to skip a particular file type anywhere in the repository tree. ```bash theme={null} endorctl scan --exclude-path="**/*.lock" ``` ### Combine a quick scan with an exclusion Add `--exclude-path` to `--quick-scan` to run a faster scan while skipping a specific path. ```bash theme={null} endorctl scan --quick-scan --exclude-path="src/java/generated/**" ``` ### Exclude a directory at any depth Use a leading `**/` to match a directory name regardless of where it appears in the repository tree. This is useful for directories like `node_modules` that can appear at multiple levels. ```bash theme={null} endorctl scan --exclude-path="**/node_modules/**" ``` ## Best practices of scoping scans Here are a few best practices of using scoping scans: * Ensure that you enclose your exclude pattern in double quotes to avoid shell expansion issues. For example, do not use `--exclude-path=src/test/**`, instead, use `--exclude-path="src/test/**"`. * Inclusion patterns are not designed for documentation or example directories. You cannot explicitly include documentation or example directories: * `docs/` * `documentation/` * `groovydoc/` * `javadoc` * `man/` * `examples/` * `demos/` * `inst/doc/` * `samples/` * The specified paths must be relative to the root of the directory. * If you are using **JavaScript** workspaces, Endor Labs automatically detects workspace roots and their lock files: * You can scan individual workspace packages without explicitly including the root package. The scanner automatically detects the workspace root and locates the lock file. * For example, to scan only a specific workspace package: `endorctl scan --include-path="packages/utils/**"` - the scanner automatically finds and uses the lock file at the workspace root. * You can still exclude specific child packages from your scan while the workspace root is automatically detected. # endorctl CLI exit codes Source: https://docs.endorlabs.com/best-practices/troubleshooting/endorctl-exitcodes/index Learn about the exit codes that you may encounter while using the endorctl CLI. The endorctl exit codes indicate whether the program completed successfully or encountered an error. This page documents the possible endorctl exit code values and the recommended next steps. When contacting support, provide the error code and the error message to help us debug the issue. To get the exit code, run `echo $?` on the command line prompt. # Firewall & Proxy Rules Source: https://docs.endorlabs.com/best-practices/troubleshooting/firewall-rules/index Learn about firewall and web proxy rules for using Endor Labs. Your environment may need firewall or web proxy rules to use Endor Labs. Traffic flows in two directions: * **Egress**: Connections from your environment to Endor Labs, such as users accessing the Endor Labs user interface or CI systems calling the API. * **Ingress**: Connections from Endor Labs to your environment, such as scans that access self-hosted source code management (SCM) systems or private artifact registries. ## Egress rules Allow outbound HTTPS connections from your environment to the following Endor Labs endpoints. `docs.endorlabs.com` and `elprodoss.blob.core.windows.net` don't have static IP addresses. Allowlist these endpoints by domain name. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. If you have configured integrations with third-party applications like Jira, you may need additional egress rules to complete that integration. Consult the documentation for those applications to add the required rules. For better performance, the Endor Labs client, `endorctl`, may attempt to connect to dynamically managed Endor Labs cloud resources not listed above. Egress restrictions that prevent such connections will not limit Endor Labs' functionality. ## Ingress rules for restricted environments Endor Labs scans use dynamic IP addresses by default. If your environment requires IP allowlisting for firewall rules, contact Endor Labs support to enable Network Address Translation (NAT), which routes this traffic through a static IP address. You need NAT IP allowlisting for: * **Self-hosted source code management systems**: Bitbucket Data Center or self-hosted GitLab instances behind a firewall that Endor Labs needs to access for organization sync and repository cloning. * **IP-restricted cloud SCMs**: Cloud-based source code management systems that enforce IP allowlisting for app installations and API access. * **Self-hosted artifact registries**: Private artifact repositories that Endor Labs needs to access during dependency resolution in monitoring scans. * **IP-restricted webhook receivers**: Webhook endpoints that accept traffic only from allowlisted IP addresses and need to receive notifications from Endor Labs. When scans run within a private environment such as CI pipelines or Outpost-scheduled SCM App scans, NAT configuration is not required. ### Configure NAT IP allowlisting To enable NAT IP allowlisting for your tenant: 1. Contact Endor Labs support to enable NATed network requests for your tenant and obtain the NAT IP address. 2. Configure firewall ingress rules to allow HTTPS (port 443) traffic from the provided Endor Labs NAT IP address to your internal resources. ## Proxy configuration If machines in your environment connect to the internet through a web proxy, you must also configure proxy settings for `endorctl` scans, CI runners, and REST API access. See [Configure proxy server settings](/platform-administration/proxy-server-configuration) to set the required environment variables. # Troubleshooting Source: https://docs.endorlabs.com/best-practices/troubleshooting/index Diagnose and resolve common issues with Endor Labs scans. Find solutions to common issues with Endor Labs scans and tools. Learn about the exit codes for endorctl commands. Learn about the firewall rules that may be required to use Endor Labs. Learn how to scan container images built using Podman. # Scanning Podman built container images Source: https://docs.endorlabs.com/best-practices/troubleshooting/podman/index Troubleshoot errors while scanning container images built using Podman To successfully run endorctl scans on a container image built using Podman, use the following instructions: 1. Build the image using the following command. This command builds a container image and tags it with the label `test:latest`. ```bash theme={null} podman build -t test:latest ``` 2. After building the image, confirm the target registry by running the following command. Podman automatically adds `localhost` as the target registry for this image. ```bash theme={null} podman image ls ``` 3. Before scanning the image with endorctl, sign in to the registry that hosts the image. 4. Check if there is a registry running at `localhost`. 5. If a registry is not running at `localhost`, then you must re-tag the image to a reachable registry, using the following command. Replace `` with the actual URL of an accessible registry. ```bash theme={null} podman tag test:latest /test:latest ``` 6. Sign in to the reachable registry using any container runtime. Now you can run the `endorctl` scan. Targeting a reachable registry lets you locate the image manifest and download all required layer blobs for vulnerability analysis. # endorctl changelog Source: https://docs.endorlabs.com/developers-api/cli/changelog/index Version-by-version changes to the endorctl CLI. The following changes were introduced in endorctl: * Fixed `--segment-match-languages=c` so that host toolchain validation is scoped to C when `--languages` is not set, allowing C-only scans to run without failing on missing toolchains for unrelated languages. * Scala scans now log `sbt` command output, so a failing `sbt` command surfaces its build diagnostics in the scan logs. * The PR-incremental dependency resolution filter is now enabled by default for the .NET plugin. * Fixed a loss of matched file paths when a new package version won a tie-break during dependency resolution, so packages retain all matched files and C function reachability results are accurate. The following changes were introduced in endorctl: * Bug fixes and miscellaneous improvements. The following changes were introduced in endorctl: * Added the `--by-severity` flag to `endorctl container remediation list-base-image-updates` so base image update options can be broken down by the severity of the findings they resolve. * Go pull request scans now resolve only the dependencies affected by the changes in the pull request, because the incremental dependency resolution filter is enabled by default for the Go plugin. * Fixed an issue where the Go plugin reused a cached package workspace across calls, which could leave linter and license results incomplete. The plugin now materializes a fresh workspace for each call. * Scheduled scans now skip re-evaluating packages whose dependency edges and code context are unchanged. This reduces scan time for recurring scans. * Fixed dependency resolution for Python `uv` projects that compute their version dynamically, for example from a Git tag. The root package is now matched by name. The following changes were introduced in endorctl: * Fixed an issue where the dependency graph and the flat dependency list could fall out of sync when segment-matched dependencies were merged, which caused reachability information to be missing for carried-over dependencies. * Fixed an issue where PR scans updated the project `scan_time`, which delayed scheduled rescans of the default branch. PR scans no longer affect default-branch scan scheduling. * Creating or updating a custom or system secret rule now triggers a scheduled full-history rescan, so findings for the new rule appear even on repositories with no recent commits. * Fixed inconsistent dependency naming in Bazel scans that use a workspace subdirectory with `--bazel-workspace-path`, so first-party call graphs are stitched together and reachability is classified correctly. * Fixed an issue where findings were re-evaluated for projects that have dependency scanning or GitHub Actions scanning disabled, which produced spurious findings. * Fixed an issue where scans of repositories with multiple GitHub Actions packages failed with dependency-resolution errors instead of resolving every sub-package. * Fixed an issue where `pnpm-lock.yaml` was omitted from the resolved `dependency_files` metadata because lock-file detection matched only the `.lock` suffix. * Python PR scans now apply incremental dependency-resolution filtering by default, which reduces PR scan time. Set `ENDOR_SCAN_INCREMENTAL_DEP_RES=false` to opt out. The following changes were introduced in endorctl: * Added Kotlin support to Bazel scans, so `kt_jvm_library`, `kt_jvm_binary`, and `kt_jvm_test` targets are covered by both software composition analysis and call graph reachability. * Fixed Bazel scans that generated malformed queries for projects using Bzlmod repositories. The following changes were introduced in endorctl: * Fixed the user interface links printed by local scans so they point to the correct regional cluster. For example, `app.eu.endorlabs.com` for the EU cluster instead of `app.endorlabs.com`. * Fixed `endorctl host-check` to detect the Maven wrapper in the project root without requiring the `--path` flag, so it no longer falls back to the system `mvn` when a wrapper is present. The following changes were introduced in endorctl: * The PR-incremental dependency resolution filter is now enabled by default for the JavaScript plugin. It also honors an explicitly pinned lock file outside the package tree with the environment variable, `ENDOR_JS_LOCK_FILE_PATH`. * Scan logs now show the actual reason a pnpm install failed instead of a generic error. * `dotnet restore` and `dotnet build` can now resolve Windows-targeted frameworks on non-Windows scan hosts when you set the environment variable, `ENDOR_SCAN_ENABLE_WINDOWS_TARGETING`. * Fixed an issue where credentials injected into `.npmrc` for dependency resolution could persist in the working tree after a scan. * Bazel scans now classify each dependency by its own ecosystem instead of inheriting the target's language, so dependencies such as Cargo and PyPI packages under one target are classified correctly. The following changes were introduced in endorctl: * Capped SARIF rule tags to a fixed allowlist of 10 tags in deterministic priority order when exporting to GitHub Advanced Security, preventing silent tag truncation and keeping rule tags consistent across exports. * `endorctl` now compares the `CODEOWNERS` file hash before updating its record during a scan, so an unchanged `CODEOWNERS` file no longer triggers unnecessary re-processing and private dependency call graph regeneration. The following changes were introduced in endorctl: * Fixed a crash in AI security review when a generated code reference had an invalid end line number. * Reduced false positives in Infrastructure as Code (IaC) findings by improving the AI evaluator prompt. * The PR-incremental dependency resolution filter is now enabled by default for the JVM plugin. * Fixed Rust scans to resolve dependencies when a `Cargo.toml` file inherits workspace fields such as `version.workspace` and `edition.workspace`. * Fixed the segment scanner to remove stale segment match dependencies when a re-scan finds no valid matches. * Fixed an error in license dependency processing caused by overly long SPDX license identifiers. The following changes were introduced in endorctl: * Added the `--segment-match-languages` flag to `endorctl scan`. * Fixed .NET call graph scans that failed on Azure DevOps repositories whose names contain spaces, by sanitizing percent-encoded characters in the temporary clone directory path. * Fixed scanning of Azure DevOps repositories that use legacy `.visualstudio.com` URLs. The following changes were introduced in endorctl: * Fixed Python dependency resolution failing with uv 0.11 and later, where trailing-space arguments to `uv pip show` caused "invalid value" errors. * Added a native secrets detector for JWK private keys, covering RSA, EC, and OKP keys in both JSON and object-literal formats. * Fixed phantom root packages with empty paths appearing in concurrent same-language monorepo scans by ignoring transient file-not-found errors during manifest discovery. * Fixed non-deterministic dependency loss in Gradle multi-root repositories. * Python dependency-resolution failures now surface the actual `uv sync` error output instead of a generic `exit status 1` message. The following changes were introduced in endorctl: * Fixed a regression that prevented scanning empty git repositories. * Ruby scans now capture resolved dependencies from `Gemfile.lock`. The following changes were introduced in endorctl: * Bug fixes and miscellaneous improvements. The following changes were introduced in endorctl: * Maven package scans now surface the underlying error when a POM fails to parse. * Maven dependency resolution now loads the `maven-bundle-plugin` extension for OSGi POMs. * Ruby scans now import bundler to parse gemspec files. The following changes were introduced in endorctl: * Fixed Azure DevOps PR scans that failed due to a false staleness check. * SBOM export by name now returns a clear error when the package version is not found. * Secret scans now perform a full rescan when an explicit rescan is requested. The following changes were introduced in endorctl: * Fixed PR identification for GitLab and Bitbucket, resolving spurious 401 errors during PR scans. * Added the `--secret-rules-file` flag to `endorctl scan` for supplying custom secret detection rules. * Improved language detection for Rust projects. * Python call graph generation now batches large projects by lines of code and available memory. * Fixed pnpm scan failures where a package referencing workspace `catalog:` dependencies could not build its lock file when scanned in isolation. The following changes were introduced in endorctl: * Superseded PR scans are now cancelled automatically, with a dedicated return code. * Deleted package versions are now tracked in scan results and scan history. The following changes were introduced in endorctl: * Fixed PR scans on shallow or partial clones, where the merge base could be unreachable and the diff silently fell back to an incorrect comparison. endorctl now deepens the clone to reach the merge base, and reports a clear error if the two branches share no history. The following changes were introduced in endorctl: * Added the `--include-test-dependencies` flag to `endorctl sbom export`. * Pre-commit secret scans now flag only added lines. * Expanded secret validation coverage. * JavaScript scans now resolve call graphs for private transitive dependencies. * Improved Ruby dependency resolution in scans. The following changes were introduced in endorctl: * JavaScript scans can now fetch call graphs for private packages. * Improved error handling and return codes for local scans. * Added a return code for when the baseline is not found. * Secret scanning now applies the global allowlist during file walking for faster scans. * Fixed incomplete call graphs on large Go projects, where build metadata could exceed an internal scan buffer and silently drop required build settings. The following changes were introduced in endorctl: * Added the `--dry-run` flag to `endorctl container registry scan`. * Fixed the declared license field for compound SPDX expressions. The following changes were introduced in endorctl: * Added the `--os-reachability` flag to `endorctl container registry scan`. * Added Harbor as a container registry type option. * JavaScript scans now support a custom lock file location. * Fixed a JavaScript call graph failure that could cause findings to be deleted. * Private SCM dependency resolution across organizations is now enabled by default. * Added secret detection rules for Azure AD client secrets (canonical Q\~ format) and Azure Storage Account Keys, including a validator. * Fixed authentication gaps in `.npmrc` file handling. * GitHub SARIF writes now retry transient 401 errors, with clearer GitHub authentication error classification. * SBOM export now skips malformed packages instead of failing the entire export. The following changes were introduced in endorctl: * Fixed a Gradle issue where dependencies that failed manifest discovery were silently dropped, which inflated reported success rates. The resolver now synthesizes a path-derived package name so these scan failures are reported accurately. * Fixed SBOM imports where SPDX documents with multiple root packages would silently abort and return zero findings. Multi-root SPDX documents are now normalized to a single root before CycloneDX conversion, so imports succeed and vulnerability matching runs. The following changes were introduced in endorctl: * Added environment variable support for the `scanned-only` and `exclude-scanned` flags in `container registry list`, with validation that enforces mutual exclusivity between the flags and their environment variables. * Added environment variable support (`ENDOR_CONTAINER_COLLECT_*`) for the `kubeconfig-context`, `kubeconfig-path`, and `runtime-type` flags in `container collect`, with early validation of the kubeconfig context and runtime type. The following changes were introduced in endorctl: * Dependencies whose license category cannot be determined now report a category of `Unknown` instead of an empty value, so they filter consistently by license category. The following changes were introduced in endorctl: * Dependency metadata now includes declared and discovered SPDX license identifiers. * Added Google Artifact Registry (GAR) support for container registry scanning, including authentication and `gar` as a `--type` option on `endorctl container registry`. * The `--image` and `--image-tar` flags now apply only to the `container scan`, `instrument`, and `collect` commands. The `container registry` subcommands no longer accept them. * Added a warning message when the default branch is switched during a scan. * Fixed call graph generation for Java and Scala to use the JDK at `JAVA_HOME` before falling back to `PATH`, so the call graph uses your configured JDK. * Bazel targets are now resolved at the start of a scan, improving accuracy of the Bazel package include filter. * Fixed C# PR segment-matching to handle workspaces with multiple package versions and non-root baseline versions. * Fixed `container scan` argument validation to check both CLI flags and `ENDOR_CONTAINER_SCAN_*` environment variables, so env-only configuration is no longer ignored. The following changes were introduced in endorctl: * Bug fixes and miscellaneous improvements. The following changes were introduced in endorctl: * NuGet dependency scans now extract license information from a package's LicenseUrl when it is not otherwise declared, improving license coverage for NuGet projects. The following changes were introduced in endorctl: * Added the `--insecure` flag (env var `ENDOR_CONTAINER_REGISTRY_INSECURE`) to `endorctl container registry` commands, which skips TLS verification when connecting to self-signed container registries. * Renamed the environment variable for `--registry-namespace` from `ENDOR_CONTAINER_REGISTRY_REGISTRY_NAMESPACE` to `ENDOR_CONTAINER_REGISTRY_NAMESPACE`. The following changes were introduced in endorctl: * Fixed pnpm workspace detection failing when pnpm emitted WARN lines for unresolvable variables in `.npmrc` files. * Fixed secret policies not matching when a custom secret rule's name differed from its description. The result name is now sourced from the rule name. * Added `oci` as a supported registry type for container scanning, enabling OCI-compliant registry support. * Fixed a race condition that could delete the old default branch when a new default branch was set. * Fixed PR-incremental scans over-resolving dependencies on Gradle composite-build repositories. The Gradle resolver now honors the narrowed manifest set. * Fixed `ENDOR_SCAN_LANGUAGES=typescript` not running the JavaScript plugin. * Fixed PURL qualification for OS packages found through ELF binary cataloging in distroless images, which prevented false-positive vulnerability matches. * Fixed PR-incremental scans to source baseline context from the baseline repository version instead of querying all packages. * Deprecated the `--registry` flag on `endorctl container registry`. It is now replaced by `--host`. * Fixed PR-incremental Java scans triggering full Gradle resolution when no Gradle manifest survived the PR filter. * Fixed include-path validation to reject directory paths without `/*` or `/**` when set through environment variables, matching the behavior of the CLI flags and preventing accidental package deletions. * Reordered path validation so include and exclude paths are validated before `.gitignore` paths are applied. * Deprecated the `--registry-type` flag on `endorctl container registry`. It is now replaced by `--type`. The following changes were introduced in endorctl: * Fixed a nil-pointer crash in the JavaScript call graph, which could segfault scans of some npm packages. * Fixed the scan end time not being recorded on successful workflow scans, which caused the Scanned column to show an incorrect time. * Fixed AI security-review findings being silently dropped when the model classified them as new features or other aspect types. * Removed the Hugging Face organization scan flags from endorctl scan. Hugging Face organization scanning is now configured through SCM integrations in the UI. * Dependency resolution now always runs for full scans and is skipped only for quick scans. * Project summary calculation is now capped at 60 seconds for non-cloud scans, preventing scans from hanging. * Fixed Yarn workspace SBOMs being non-deterministic, which had caused flapping results and dropped roughly 2,500 transitive development dependencies. The following changes were introduced in endorctl: * Fixed an issue where credentials and tokens could leak into logs, scan results, and serialized configuration. * Fixed duplicate findings that could override scan results when the SBOM context lacked an identifier. * Fixed a nil-pointer crash that could occur when checking invalid file or directory paths during a scan. * Added an opt-in windowed incremental mode for secrets scans, enabled with `SECRETS_USE_WINDOWED_INCREMENTAL`, that splits long scans into time windows with per-window checkpoint persistence. * Added support for `--diff-scope` with `--secrets`, so secrets scans can be limited to changed files. * Fixed incremental scans so that deleted files are included when detecting dependency impact. * Fixed the host version check to retry on transient HTTP errors, reducing spurious failures. The following changes were introduced in endorctl: * The `--registry-type` flag is now optional for most container registries. Only self-hosted registries still require it. * Improved vulnerability matching for Chainguard and Wolfi apk container images through namespace canonicalization. * Fixed uv dependency resolution for `pyproject.toml` package names containing underscores, following PEP 503 normalization. * Fixed call graph errors on Yarn Berry Plug'n'Play projects by forcing the node-modules linker. * Fixed sbt dependency parsing for Maven version ranges and version evictions in `.dot` output. * The `--reauth` flag is now marked experimental. Users are directed to credential helpers instead. * Fixed Bazel Build Event Protocol nested fileset parsing. * GitHub check-run annotations now show correct finding counts for security review after low-severity filtering. * Fixed .NET call graph normalization for private packages that have no DLLs. * Fixed a crash in the MCP security review tool and wired in aspect-based classification. The following changes were introduced in endorctl: * The `--publish` flag on `endorctl container instrument` now pushes the instrumented image to the registry automatically after instrumentation. The following changes were introduced in endorctl: * Added a `--platform` flag to `endorctl container instrument` that accepts a comma-separated list of platforms, so you can instrument container images for multiple architectures such as arm64 and amd64 in a single command while preserving the multi-arch manifest. * Improved Bazel Bzlmod scanning to better detect JavaScript dependencies. * Faster secret scanning on Linux from an upgraded secret-detection engine with native RE2 regex support. The following changes were introduced in endorctl: * Private Git-based dependencies hosted in other GitHub organizations or GitLab groups now resolve for Go, SwiftPM, Python, Node.js, Rust, and Ruby. * The AI SAST evaluator now produces more consistent security review results. * The default `--timeout` for `endorctl container registry` changed from `30s` to `0s`, so registry scans run without timing out. * C is now an officially supported language. The following changes were introduced in endorctl: * Host checks now gate container operations on Windows and emit a warning when prerequisites are not met. * `Unable to process dependencies` errors now surface under Issues with a Partial Success scan status instead of only appearing in logs. * Merge-to-main lookback is now enabled by default, so incremental PR scans consult recent merge-to-main package versions to avoid duplicate findings across pull requests. * Bazel scans now fail gracefully on non-executable targets instead of erroring out. * Scan requests now complete instead of staying stuck in progress when a GitHub check-run update fails. * C# segment scans now handle package versions that use non-native path separators. * JavaScript and npm phantom dependencies are now correctly tagged as phantom and marked transitive instead of direct. * TypeScript call graph generation now handles race conditions for more reliable scans. The following changes were introduced in endorctl: * Fixed Yarn dependency graphs that contained dangling edges when alias * Fixed the Scala fallback path stripping version suffixes from package names, which previously caused scans to be rejected. * Yarn version detection now prefers the lockfile format over the installed runtime binary version. The following changes were introduced in endorctl: * JavaScript scans start faster because the plugin now lazy-loads its TreeSitter queries. * .NET scans now attempt a solution-level dotnet restore before falling back to per-project restore. * The `--base-image-scan` flag on `endorctl container scan` now defaults to `true`, so base image scanning runs by default. * Filesystem secret scans now respect the `--include-path` and `--exclude-path` flags. * Dependency resolution is now correct when a monorepo root and a workspace child share the same package name. * .NET scans now suppress the .NET SDK first-run welcome banner, which previously interfered with MSBuild property extraction. * JavaScript scans of non-workspace monorepos now check the repository root `node_modules` when resolving subpackage lockfiles. The following changes were introduced in endorctl: * Java dependency resolution now requires actual artifact detection. The legacy identification of dependencies without Java artifacts has been removed. * Added Python support for Bazel scans through the `rules_python` aspects plugin. * Raised the custom tag maximum length from 63 to 255 characters. * Added Swift support for Bazel scans through the `rules_swift` aspects integration. * Python scans now auto detect unlisted `.txt` files as pip requirements through content analysis, beyond the files passed with the requirements-file option. * Increased the default scan timeout from 10 minutes to 30 minutes. The following changes were introduced in endorctl: * Fixed a failure scanning Java projects that use private registries over mTLS by merging your custom CA into the default truststore, so public and private dependencies both resolve. * Lifecycle scripts are now suppressed during dependency resolution for pnpm, Yarn Berry, and Rush installs, preventing arbitrary code execution. * .NET scans now evaluate complex MSBuild property expressions using native MSBuild property evaluation, with a static XML fallback. The following changes were introduced in endorctl: * JavaScript call graph generation now fails with a clear error when `node_modules` were not fully downloaded, instead of producing incorrect results. * C# builds now preserve the order of imported prop files in `.csproj` projects, correcting .NET dependency resolution. * .NET scans now shut down the MSBuild build server, preventing orphaned worker processes from accumulating between retries. * Incremental PR scans now match root-level packages correctly when the baseline uses `pr/*` version tags. * Incremental PR scans now handle segment-match dependencies correctly for C/C++ and C# projects. The following changes were introduced in endorctl: * Reduced the default Maven connect timeout to 30 seconds and read timeout to 60 seconds so scans against slow package repositories fail faster. * Added Quay container registry support to the `endorctl container registry list` and `endorctl container registry scan` commands. * Fixed .NET package name mismatches by assigning unresolved package names to the resolved package and call graph response. * Fixed incorrect package names for Python projects that use a dynamic version field in `pyproject.toml`. * Secret scanning of git logs now assumes files are git tracked, so findings from historical commits are included. * Java scans now skip the OWASP dependency-check Maven plugin during the mvn install build step, avoiding a 212MB NVD database download. The following changes were introduced in endorctl: * PR scans now fall back to a full-history fetch when baseline refs are missing, improving baseline comparison reliability. * Fixed Bazel `scala_library` call graph generation to resolve the correct artifact path. * Added support for the latest `rules_python` hermetic toolchain runfile locations in Bazel Python call graphs. * Yarn scans now respect the `yarnPath` and `nodeLinker` settings in `.yarnrc.yml` and handle Yarn registry credentials more reliably. * Fixed SPDX SBOM import failures caused by temporary path collisions. * Fixed false positive package detection where module `setup.py` files were misclassified as setuptools manifests. * Policy validation now checks for typos in customer-authored policies, surfacing clearer validation errors. The following changes were introduced in endorctl: * Fixed a crash when normalizing Python package names with malformed coordinates. * Fixed a Docker client connection leak that could accumulate during container scans. * Fixed missing pedigree information in SBOM output, including patch and purl fields, with purl now used for dependency lookups. * Added the `endorctl ignore` command that adds findings or vulnerability IDs to the ignore file, which dismisses findings during scans. * Added the `endorctl validate ignore` command that validates the ignore file syntax. * The Go registry resolver now handles standard library packages, including direct download and metadata. * Fixed handling of URL-encoded slashes in function reference versions for .NET and Java call graphs. # ai-audit Source: https://docs.endorlabs.com/developers-api/cli/commands/ai-audit/index Process AI coding agent hook events for Coding Agent Governance. The command `endorctl ai-audit` processes AI coding agent hook events for [Coding Agent Governance](/agent-governance). You do not run it interactively. A hook configuration installed on a developer machine invokes it once per hook event. The agent passes the event as JSON on standard input, and the command writes the agent-specific response, such as an allow or deny decision, to standard output. See [Deploy hooks for Cursor](/agent-governance/cursor), [Claude Code](/agent-governance/claude-code), [Codex](/agent-governance/codex), and [GitHub Copilot](/agent-governance/copilot) to install the hook configurations that run this command. ## Usage Each supported agent has a subcommand that understands that agent's hook payload format. ```bash theme={null} endorctl ai-audit ``` A typical hook configuration entry runs the command with explicit connection flags. ```bash theme={null} endorctl --api $ENDOR_API --namespace $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ai-audit cursor ``` ## Authentication `endorctl ai-audit` authenticates with an API key and secret issued for the **AI Audit User** role. See [Prerequisites for Coding Agent Governance](/agent-governance/prerequisites) to create the key. Unlike other endorctl commands, `ai-audit` ignores `ENDOR_TOKEN` when API key credentials are present, so hooks keep working in shells that already exported a token. Older versions of endorctl failed on the mixed credentials, so don't export `ENDOR_TOKEN` in the hook environment. See [endorctl exit codes](/best-practices/troubleshooting/endorctl-exitcodes) for the related authentication failure. ## Behavior The command has the following runtime behavior: * **Local policy evaluation**: The command evaluates each event against the policy snapshot in `~/.endorctl/aigovernance/endor-policies.jsonl`. The snapshot refreshes from your namespace at session start, so pattern-based enforcement needs no network round-trip per event. Malware policies are the exception, querying the malware feed per matching install. See [Local policy cache](/agent-governance/policies#local-policy-cache). * **Fails open**: If the command cannot run, or cannot reach the Endor Labs API for a malware verdict, it allows the action rather than blocking the agent. An unparseable policy snapshot falls back to the built-in system policies. * **Bounded latency**: Each invocation limits itself to 5 seconds, then fails open, so a backend outage cannot stall the agent. ## Environment variables For an audit-only rollout, set `ENDOR_AI_AUDIT_NO_BLOCKING=true` in the environment of the hook, as shown in the deploy configuration for each agent. It downgrades every Block action to Alert at evaluation time, so policies record violations without denying actions. ## Related information The following pages cover the feature this command serves: * [Coding Agent Governance](/agent-governance) for what the hooks capture and enforce. * [How Coding Agent Governance works](/agent-governance/how-it-works) for the event lifecycle and the data sent to Endor Labs. * [Deploy Coding Agent Governance with MDM](/agent-governance/mdm-deployment) to generate hook configurations for managed fleets. # api Source: https://docs.endorlabs.com/developers-api/cli/commands/api/index Use the api command to interact with the Endor Labs API. The `endorctl api` command allows you to interact with the Endor Labs API directly through the command line interface. ## Usage The syntax of the `endorctl api` command is: ```bash theme={null} endorctl api [subcommand] [flags] ``` The `endorctl api` command supports the following subcommands: * `create` creates a specified object in a namespace. * `delete` deletes a specified object in a namespace. * `get` gets a specified object in a namespace. * `list` lists a specified group of objects in a namespace. * `update` updates a specified object in a namespace. ### Flags and variables The `endorctl api` subcommands support the following flags, unless specified otherwise: ### Commonly used resource types The following table lists resource types that are commonly used in the API. See [resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds) for more information. Resource kinds are case sensitive. ## endorctl api create The `endorctl api create` command creates an object of a specified resource type. ```shell theme={null} endorctl api create -r [resource] [flags] ``` ### endorctl api create interactive mode * Use `--interactive` or `-i` to create an object with an interactive code editor. * Define your editor using `export EDITOR=` where the editor is the command you use to edit files. For example, `export EDITOR=vi` allows you to edit in vi and `export EDITOR=code` opens the file with the code command in VS Code. ### endorctl api create examples To create a package manager integration that uses the repository `https://example.replaceme.com` for dependency resolution in Python with the top priority for dependency resolution use the following command. ```shell theme={null} endorctl api create -r PackageManager \ --data '{"meta":{"name":"pypi PackageManager"},"spec":{"pypi":{"url":"https://example.replaceme.com ","priority":0}}}' ``` ## endorctl api delete The `endorctl api delete` command deletes a given object of a specified resource type. ```shell theme={null} endorctl api delete -r [resource] [flags] ``` ### endorctl api delete example Use the following command to delete the project with the UUID, '62aa1cfadfa47d9ccb754d22', that is no longer needed. ```shell theme={null} endorctl api delete -r Project --uuid 62aa1cfadfa47d9ccb754d22 ``` ## endorctl api get The `endorctl api get` command retrieves a given object of a specified resource type. ```shell theme={null} endorctl api get -r [resource] [flags] ``` ### endorctl api get examples * Get a specific project by its UUID. ```shell theme={null} endorctl api get -r Project --uuid ``` * Get a specific package version. ```bash theme={null} endorctl api get --resource "PackageVersion" --name "://@" ``` ## endorctl api list The `endorctl api list` command lists all objects of a specified resource type, based on the specified filters, field-masks and/or other options. ```shell theme={null} endorctl api list -r [resource] [flags] ``` ### endorctl api list flags and variables The `endorctl api list` command supports the following additional flags and environment variables: ### endorctl api list examples Use the `--filter` flag to customize your query and the `--field-mask` flag to limit the fields returned. For example, run the following command to list the description and the target dependency name for all findings in a given project. ```shell theme={null} endorctl api list \ --resource Finding \ --filter "spec.project_uuid==" \ --field-mask "meta.description,spec.target_dependency_package_name" ``` See [Filters](/developers-api/rest-api/using-the-rest-api/filters) and [Masks](/developers-api/rest-api/using-the-rest-api/masks) for more information on filters and field-masks. Get a count of the number of projects hosted in your Endor Labs tenant. ```bash theme={null} endorctl api list \ --resource Project \ --count \ | jq -r '.count_response.count' ``` List all projects in the namespace and only return the name of each project. ```shell theme={null} endorctl api list \ --resource Project \ --list-all \ --field-mask meta.name \ | jq '.list.objects[].meta.name' ``` List all package versions at a given source code Git reference. ```bash theme={null} endorctl api list \ --resource "PackageVersion" \ --output-type "yaml" \ --filter "spec.project_uuid== and spec.source_code_reference.version.ref==" ``` List all direct dependencies of a specific package given its UUID. ```bash theme={null} endorctl api list \ --resource DependencyMetadata \ --filter "spec.importer_data.package_version_uuid== and spec.dependency_data.direct==true" ``` Return a count of findings associated with the default branch for a given project. ```shell theme={null} endorctl api list \ --resource Finding \ --filter "context.type==CONTEXT_TYPE_MAIN and spec.project_uuid==" \ --count ``` Return a count of unique vulnerabilities in non-test dependencies for a given project. Filters to vulnerabilities with an upstream patch available and a reachable function. ```shell theme={null} endorctl api list \ --resource Finding \ --filter "context.type==CONTEXT_TYPE_MAIN and spec.project_uuid== and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and spec.finding_tags contains [FINDING_TAGS_NORMAL] and spec.finding_tags contains [FINDING_TAGS_REACHABLE_FUNCTION] and spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE]" \ --group-aggregation-paths "spec.finding_metadata.vulnerability.meta.name" ``` Return the count of the number of scans run on the default branch since a given date. ```shell theme={null} endorctl api list \ --resource ScanResult \ --filter "context.id==default and meta.create_time >= date(2023-11-14)" \ --count ``` See [Use cases](/developers-api/rest-api/using-the-rest-api/use-cases) for more examples. ## endorctl api update ```shell theme={null} endorctl api update -r [resource] [flags] ``` ### endorctl api update interactive mode * Use `--interactive` or `-i` to update an object with an interactive code editor. * Define your editor using `export EDITOR=` where the editor is the command you use to edit files. For example, `export EDITOR=vi` allows you to edit in vi and `export EDITOR=code` opens the file with the code command in VS Code. * Specify which fields you want to update using the `--field-mask` parameter. If this is not set, endorctl will try to update all fields. ### endorctl api update examples To interactively update a project with the UUID 6549886f0dd828140b4a477b. ```shell theme={null} endorctl api update -r Project -i --uuid 6549886f0dd828140b4a477b --field-mask meta.tags ``` To add a tag "CrownJewel" to a project named [https://github.com/endorlabs/github-action](https://github.com/endorlabs/github-action) use the following command. ```shell theme={null} endorctl api update -r Project \ --name https://github.com/endorlabs/github-action \ --data "{ \"meta\": {\"tags\": [ \"CrownJewel\" ] }}" \ --field-mask 'meta.tags' ``` # completion Source: https://docs.endorlabs.com/developers-api/cli/commands/completion/index Use the completion command to get a command completion script for a specified command shell The `completion` command for endorctl outputs a completion script that you can add to your local environment. After running the script, tab autocompletion will be available for endorctl. Supported command completion environments are Zsh, PowerShell, bash and fish. ## Command completion for Zsh shells To enable command completion for a macOS based Zsh environment. ```shell theme={null} echo "source $(endorctl completion zsh)" >> ~/.zshrc source ~/.zshrc ``` You will need to start a new shell for this setup to take effect. ## Command completion for bash shells To enable command completion for a Linux bash based shell. ```shell theme={null} echo "source $(endorctl completion zsh)" >> ~/.bashrc source ~/.bashrc ``` You will need to start a new shell for this setup to take effect. ## Command completion for PowerShell To load completions in your current shell session. ```powershell theme={null} endorctl completion powershell | Out-String | Invoke-Expression ``` To load completions for every new session, add the output of the above command to your PowerShell profile. ## Command completion for Fish shells To load completions in your current shell session. ```shell theme={null} endorctl completion fish | source ``` To load completions for every new session, execute once. ```shell theme={null} endorctl completion fish > ~/.config/fish/completions/endorctl.fish ``` You will need to start a new shell for this setup to take effect. ## Usage There are no flags that apply to endorctl completion. # container Source: https://docs.endorlabs.com/developers-api/cli/commands/container/index Use the container command to scan and operate on container images. Run the `endorctl container` command to scan container images, instrument them for reachability analysis, collect data from deployment environments, and perform registry operations. ## Usage The syntax of the `endorctl container` command is: ```bash theme={null} endorctl container [command] [flags] ``` The `endorctl container` command supports the following subcommands: * `scan`: Scans a container image for vulnerabilities and security risks. * `instrument`: Instruments a container image with the dynamic profiling sensor. * `collect`: Collects data from the target deployment environment. Use the `endorctl container scan` command instead of the deprecated `endorctl scan --container` command. See [Container scan commands migration guide](/scan/containers/container-migration) for more information. ## Run the endorctl scan Endor Labs supports the following methods of scanning container images: * **[Scan container images in a Git repository](#scan-container-images-in-a-git-repository)**: Use this approach to scan images built within your repository using a Dockerfile. * **[Scan container images as a standalone project](#scan-container-images-as-a-standalone-project)**: Use this approach to scan base or golden images that you share across multiple repositories or applications. * **[Scan container image tarball](#scan-container-image-tarball)**: Use this to scan images saved as tar files, such as base images exported from Docker, to generate dependency, SBOM, and vulnerability reports. ### Scan container images in a Git repository Run the following command to scan a container image built in a specific repository. Specify the project path using the `--path` argument and the container image name using the `--image` argument. This associates the container with the Git repository and branch of the project. ```bash theme={null} endorctl container scan --image= --path=users/janedoe/endorlabs/npm/exampleproject ``` You can also scan multiple container images as part of a single repository. ```bash theme={null} endorctl container scan --image= --path=users/janedoe/endorlabs/npm/exampleproject endorctl container scan --image= --path=users/janedoe/endorlabs/npm/exampleproject endorctl container scan --image= --path=users/janedoe/endorlabs/npm/exampleproject ``` You can tag findings with the corresponding container image name and tag. This lets you filter container-related findings in the user interface or through the API. ```bash theme={null} endorctl container scan --image= --path=users/janedoe/endorlabs/npm/exampleproject --finding-tags= ``` ### Scan container images as a standalone project Run the following command to scan a container image from a registry. Specify the project name using the `--project-name` argument, and the container image name and tag using the `--image` argument. ```bash theme={null} endorctl container scan --image= --project-name= ``` To keep multiple versions of a container image in a container-only project, include the `--as-ref` flag. ```bash theme={null} endorctl container scan --image= --project-name= --as-ref ``` You can tag findings with the corresponding container image name and tag. This lets you filter container-related findings in the user interface or through the API. ```bash theme={null} endorctl container scan --project-name= --image= --as-ref --finding-tags= ``` **Important** To associate a container scan with an existing SCA scan for a project, you must use the `--path` argument specifying the same project path used for the SCA scan. You cannot associate a container scan with an SCA scan for a project using the `--project-name` parameter. ### Scan container image tarball You can save a container image as a tarball and scan it with endorctl to generate a report containing dependencies, SBOM details, and security findings. 1. Ensure that you have the container image available locally. ```bash theme={null} docker pull alpine:latest ``` 2. Export the image to a tarball file. ```bash theme={null} docker save alpine:latest -o alpine-latest.tar ``` 3. Perform the endorctl scan. ```bash theme={null} endorctl container scan --image=alpine:latest --project-name= --image-tar=/absolute/path/to/alpine-latest.tar ``` * `--image-tar` must point to the absolute path of the tarball file. * `--image=` is optional but recommended. It explicitly identifies the container image inside the tarball. ### Options The `endorctl container scan` command supports the following flags. ## Instrumented container reachability Instrumented container reachability records the OS packages your application uses at runtime through a sensor in your image. Use `endorctl container instrument` to create the instrumented image. See [Instrumented container reachability](/scan/containers/instrumented-reachability) for more information. The `endorctl container instrument` command supports the following flags. ### Collect container profiling data The `endorctl container collect` command collects data from the target deployment environment, including profiling data from instrumented containers. See [Instrumented container reachability](/scan/containers/instrumented-reachability#determine-instrumented-container-reachability) for the full workflow. The `endorctl container collect` command supports the following flags: ## Container registry scanning A container registry is a centralized service that stores and distributes your container images. Endor Labs lets you scan images directly from your registry, giving you full visibility into the security posture of your containerized workloads at scale. Use the `endorctl container registry` commands to list and scan images stored in your registry. * [**List images from a registry**](#list-command): Use `endorctl container registry list` to preview which images match your filters before scanning. This lets you verify the scope and adjust filtering parameters such as `--include`, `--exclude`, `--recent`, and `--limit`. You can also save the results as a scan plan for the scan step. * [**Scan images from a registry**](#scan-command): Use `endorctl container registry scan` to enumerate and scan container images from a registry in a single step. You can also provide a saved scan plan from the list command instead of enumerating the registry again. **Prerequisites for AWS ECR, Azure ACR, and Google Artifact Registry scans** * **AWS ECR**: Install and configure the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). * **Azure ACR**: Install and configure the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli). * **Google Artifact Registry**: Install the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) and run `gcloud auth configure-docker -docker.pkg.dev` to configure the Docker credential helper. Replace `` with your registry region, such as `us-west2`. ### List command The list command connects to your registry, enumerates container images based on your configured filters, and prints a summary with a table of image paths. You can also save the results as a scan plan to reuse with the scan command. ```bash theme={null} endorctl container registry list --type= [options] ``` You can apply filters such as `include`, `exclude`, `recent`, and `limit` to narrow down the images returned. If you provide a namespace and API credentials, the saved plan automatically excludes already scanned images, so it is ready to scan only new or updated images. The command applies filters in the following order: 1. **include** 2. **exclude** 3. **recent** 4. **limit** You can use the `endorctl container registry list` command with the following flags. ### Scan command The scan command runs Endor Labs container scans on a set of images. You can pass a saved scan plan from the list command or enumerate the registry with the same filter flags as list. The command pulls each image if needed, runs the scan, and by default removes pulled images after scanning. You must provide `--namespace` and API credentials. Images that are already scanned are automatically skipped. * Scan using a saved scan plan: ```bash theme={null} endorctl container registry scan --namespace= --scan-plan= [options] ``` * Scan using a registry type. When you do not use `--scan-plan`, pass `--type`. ```bash theme={null} endorctl container registry scan --namespace= --type= [options] ``` You can use the `endorctl container registry scan` command with the following flags. # help Source: https://docs.endorlabs.com/developers-api/cli/commands/help/index Use the help command to get command help for endorctl. The help command lists all available commands for endorctl scan. ## Examples ```shell theme={null} endorctl help ``` ## Usage ```shell expandable theme={null} endorctl help Endorctl is a command-line tool that allows you to scan and monitor your projects, import and export SBOMs, and interact with the API. Using endorctl you can connect to your Endor Labs tenant and integrate it into your CI pipeline. Usage: endorctl [flags] endorctl [command] Available Commands: api Interact with the Endor Labs API completion Generate the autocompletion script for the specified shell help Help about any command host-check Validate host machine environment and configuration init Initialize or reinitialize endorctl recommend Recommendations for dependency maintenance sbom SBOM operations scan Scan a source code repository sync-org Sync GitHub repositories for a specified organization validate Validate a policy Flags: -a, --api string Set the API URL for the Endor Labs Application (default "https://api.endorlabs.com") --api-key string Set the API key used to authenticate with Endor Labs --api-secret string Set the secret corresponding to the API key used to authenticate with Endor Labs --aws-role-arn string Set the target role ARN for AWS based authentication. AWS authentication is only enabled if this flag is set --bypass-host-check Bypass the check that verifies that the host machine is correctly setup to use endorctl --config-path string Set the local filesystem path to the endor config directory containing your endor environment variables --enable-github-action-token Enable keyless authentication using Github action OIDC tokens --gcp-service-account string Set the target service account for GCP based authentication. GCP authentication is only enabled if this flag is set -h, --help help for endorctl --log-level string Set the log level (default "info") -n, --namespace string Set to the namespace of the project that you are working with --token string Set the authentication token used to authenticate with Endor Labs --verbose Enable verbose logging -v, --version version for endorctl Use "endorctl [command] --help" for more information about a command. ``` If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. # host-check Source: https://docs.endorlabs.com/developers-api/cli/commands/host-check/index Use the host check command to verify if your system is appropriately set up to perform a scan. The command `endorctl host-check` verifies if your system can perform a successful scan. ## Usage To verify that your local host is appropriately configured to scan a given repository: 1. Clone the repository for which you'd like to verify system setup. Update the following instructions to the repository of your selection. ```shell theme={null} git clone https://github.com/endorlabs/app-java-demo.git ``` 2. Navigate to the root of the repository you've cloned. ```shell theme={null} cd ./app-java-demo ``` 3. Run the `endorctl host-check` command. ```shell theme={null} endorctl host-check ``` ## Options The `endorctl host-check` command uses the following flags and environment variables. # ignore Source: https://docs.endorlabs.com/developers-api/cli/commands/ignore/index Use the ignore command to add findings to the ignore file. Use the `ignore` command to add findings or vulnerability IDs to the ignore file, which dismisses findings during scans. This allows developers to request exceptions directly in their pull requests and provides teams with the option to manage exceptions directly in the source code. You must [enable ignore file support](/platform-administration/configure-system-settings#allow-ignore-files-to-dismiss-findings) in **Settings** > **SYSTEM SETTINGS** > **Developer Workflows** for ignore files to be processed during scans. ## Usage The syntax of the `endorctl ignore` command is: ```bash theme={null} endorctl ignore [--finding-uuid | --vuln-id ] [-i] [flags] ``` You must provide `--finding-uuid`, `--vuln-id`, or `--interactive`. If you provide a finding UUID, you must also provide `--namespace`. The more fields you provide, the more specific the ignore entry. For example, if you provide the finding name and multiple findings share that name in the same repository version, the command applies the ignore entry to all such findings. ## Options The command `endorctl ignore` uses the following flags and environment variables: ## Examples ### Ignore a finding based on UUID Ignore a specific finding based on the UUID and enter details such as reason and expiration-date interactively: ```bash theme={null} endorctl ignore --finding-uuid $FINDING_UUID --namespace $NAMESPACE -i ``` Ignore finding UUID interactive #### Ignore entry based on finding UUID and interactive input Here the user entered the reason, expiration date, and comments interactively. The rest was automatically populated based on the finding UUID. The default prefix is the finding project name. ```yaml theme={null} version: 1.0.0 ignore: - id: endorlabs/app-java-demo-1 username: bob@corp.com@google update_time: 2026-02-09 22:35:04 UTC finding_name: Unmaintained Dependency org.webjars.bowergithub.webcomponents:shadycss@1.9.1 parent_name: mvn://com.endor.webapp:endor-java-webapp-demo@4.0-SNAPSHOT dependency_name: mvn://org.webjars.bowergithub.webcomponents:shadycss@1.9.1 extra_key: mvn://org.webjars.bowergithub.webcomponents:shadycss@1.9.1 reason: other expiration_date: 2026-03-01 comments: Will change to a better dependency in a separate commit ``` ### Enter all details interactively Enter all details about which findings to ignore interactively, without the UUID: ```bash theme={null} endorctl ignore -i ``` Ignore interactive #### Ignore entry based on interactive input only Here the user entered the finding name, reason, expiration date, and comments interactively. The default prefix is `endorignore-`. ```yaml theme={null} version: 1.0.0 ignore: - id: endorignore-1 username: bob@corp.com@google update_time: 2026-02-09 22:36:01 UTC finding_name: Unmaintained Dependency org.webjars.bowergithub.webcomponents:shadycss@1.9.1 reason: other expiration_date: 2026-03-01 comments: Will change to a better dependency in a separate commit ``` ### Automation Use command in a script to ignore findings based on UUID with a custom prefix: ```bash theme={null} endorctl ignore \ --path=$PATH_TO_IGNORE_FILE \ --prefix=$CUSTOM_PREFIX \ --namespace=$NAMESPACE \ --finding-uuid=$FINDING_UUID \ --username=$USERNAME \ --reason=$REASON \ --comments=$COMMENTS \ --expiration-date=$EXPIRATON_DATE \ --expire-if-fix-available=$EXPIRE_IF_FIX_AVAILABLE ``` # Commands Source: https://docs.endorlabs.com/developers-api/cli/commands/index Learn more about the available endorctl commands The following commands are available in endorctl: * [ai-audit](/developers-api/cli/commands/ai-audit): Process AI coding agent hook events for Coding Agent Governance. * [api](/developers-api/cli/commands/api): Interact with the Endor Labs API. * [completion](/developers-api/cli/commands/completion): Generate a command completion script for a specified command shell. * [container](/developers-api/cli/commands/container): Scan and operate on container images. * [help](/developers-api/cli/commands/help): Get command help for endorctl. * [host-check](/developers-api/cli/commands/host-check): Verify if your system is ready to perform a scan. * [ignore](/developers-api/cli/commands/ignore): Add findings to the ignore file. * [init](/developers-api/cli/commands/init): Authenticate to Endor Labs from a workstation with an external identity provider. * [recommend](/developers-api/cli/commands/recommend): Suggest dependency updates that address issues across your environment. * [rule-set](/developers-api/cli/commands/rule-set): Import SAST rules into Endor Labs. * [sbom](/developers-api/cli/commands/sbom): Import or export SBOMs to or from Endor Labs. * [sbom export](/developers-api/cli/commands/sbom/export): Export an SBOM for a software package from Endor Labs. * [sbom import](/developers-api/cli/commands/sbom/import): Import SBOMs to Endor Labs. * [scan](/developers-api/cli/commands/scan): Perform scans against a repository. * [artifact sign](/developers-api/cli/commands/sign-artifacts): Sign and verify container images and build artifacts. * [sync-org](/developers-api/cli/commands/sync-org): Sync all projects in a GitHub organization to Endor Labs. * [toolchains](/developers-api/cli/commands/toolchains): Detect tools in your repository, create a scan profile, or generate a Dockerfile. * [validate](/developers-api/cli/commands/validate): Validate policies and ignore files. * [validate ignore](/developers-api/cli/commands/validate/ignore): Validate a YAML ignore file. * [validate policy](/developers-api/cli/commands/validate/policy): Validate policies. # init Source: https://docs.endorlabs.com/developers-api/cli/commands/init/index Use the init command to authenticate to Endor Labs from a workstation with an external identity provider. The command `endorctl init` allows you to quickly authenticate your client to Endor Labs using an external identity provider. Supported authentication providers for `endorctl init` are: * `google` - Used to create an API key and API key secret when you sign in with Google Workspaces as your external identity provider. * `github` - Used to create an API key and API key secret when you sign in with GitHub Cloud as your external identity provider. * `gitlab` - Used to create an API key and API key secret when you sign in with GitLab Cloud as your external identity provider. * `email` - Used to create an API key and API key secret when you sign in with an email link. * `sso` - Used to sign in with a Custom Enterprise Identity Provider, such as Okta. ## Usage Run `endorctl init` and your browser window will open automatically. Select your authentication provider from the available options and complete the authentication process. Init authentication through browser You can also specify your supported authentication provider manually: ```bash theme={null} endorctl init --auth-mode=google ``` ```bash theme={null} endorctl init --auth-mode=github ``` ```bash theme={null} endorctl init --auth-mode=gitlab ``` ```bash theme={null} endorctl init --auth-email=`` ``` ```bash theme={null} endorctl init --auth-mode=sso --auth-tenant=`` ``` To login with your supported authentication provider in environments without a browser you can use headless mode: ```bash theme={null} endorctl init --auth-mode=google --headless-mode ``` ```bash theme={null} endorctl init --auth-mode=github --headless-mode ``` ```bash theme={null} endorctl init --auth-mode=gitlab --headless-mode ``` ```bash theme={null} endorctl init --auth-email=`` --headless-mode ``` ```bash theme={null} endorctl init --auth-mode=sso --auth-tenant=`` --headless-mode ``` Once you've issued the command in headless mode, navigate to an internet/browser accessible computer and follow the instructions provided in your terminal. ## Options The following flags and environment variables are available for the `endorctl init` command. # license-notice-report Source: https://docs.endorlabs.com/developers-api/cli/commands/license-notice-report/index Generate license notice reports for a package version from the command line. The `license-notice-report` command manages license notice reports for package versions. The report includes license texts, copyright notices, and other attribution information that should be included when distributing software that uses the specified package. The syntax of the `endorctl license-notice-report` command is: ```bash theme={null} endorctl license-notice-report [command] [flags] ``` ## Usage Use the `endorctl license-notice-report generate` command to initiate report generation for a package version: ```bash theme={null} endorctl license-notice-report generate --namespace --package-version-uuid [flags] ``` ## Options The `endorctl license-notice-report generate` command uses the following flags: See [Licenses](/inventory-insights/licenses/#generate-a-notice-report) for more information. # recommend Source: https://docs.endorlabs.com/developers-api/cli/commands/recommend/index Use the recommend command to suggest dependency updates that address issues across your environment. The `endorctl recommend` command returns prioritized updates to fix findings across your tenant, projects, or packages. Each recommendation weighs the number of issues and complexity of an upgrade. ## Usage To recommend dependency updates across **all projects** in your namespace. ```shell theme={null} endorctl recommend dependency-upgrades ``` To recommend dependency updates across a **specific project** in your namespace: 1. Retrieve the UUID of your project. In the following example, we are retrieving the UUID of the project "[https://github.com/endorlabs/app-java-demo](https://github.com/endorlabs/app-java-demo)" and saving it as an environment variable. ```shell theme={null} UUID=$(endorctl api list -r Project --filter="meta.name matches https://github.com/endorlabs/app-java-demo" --field-mask=uuid | jq -r '.list.objects[].uuid') ``` 2. Run the `recommend dependency-upgrades` command. ```shell theme={null} endorctl recommend dependency-upgrades --project-uuid=$UUID ``` To recommend dependency updates across a **specific package** in your namespace: 1. Retrieve the UUID of your package version. The following example looks for a project with the name "[https://github.com/endorlabs/app-java-demo](https://github.com/endorlabs/app-java-demo)" and saves it as an environment variable. ```shell theme={null} UUID=$(endorctl api list -r PackageVersion --filter="meta.name==mvn://com.endor.webapp:endor-java-webapp-demo@4.0-SNAPSHOT AND context.type==CONTEXT_TYPE_MAIN" --field-mask=uuid | jq -r '.list.objects[].uuid') ``` 2. Run the `recommend dependency-upgrades` command. ```shell theme={null} endorctl recommend dependency-upgrades --package-version-uuid=$UUID ``` ## Options The following flags and environment variables are available for the `endorctl recommend` command. # rule-set Source: https://docs.endorlabs.com/developers-api/cli/commands/rule-set/index Use the rule-set command to import SAST rules into Endor Labs. The `endorctl rule-set` command manages SAST rules in your Endor Labs namespace. ## Usage ```bash theme={null} endorctl rule-set [subcommand] [flags] ``` ## rule-set import The `endorctl rule-set import` command imports SAST rules from a local `.tar` or `.gz` archive into your Endor Labs namespace. Endor Labs imports every `.yaml` and `.yml` file in the archive and tags each rule with the version you specify. ```bash theme={null} endorctl rule-set import \ --namespace \ --file-path \ --rule-version ``` ### Options ### How to use rule-set command * Validate a rule archive before importing it. ```bash theme={null} endorctl rule-set import \ --namespace my-org \ --file-path ./my-rules.tar.gz \ --rule-version v1.2.0 \ --dry-run ``` * Import rules into a namespace. ```bash theme={null} endorctl rule-set import \ --namespace my-org \ --file-path ./my-rules.tar.gz \ --rule-version v1.2.0 ``` ``` ``` # export Source: https://docs.endorlabs.com/developers-api/cli/commands/sbom/export/index Use the sbom export command to export an SBOM for a software package from Endor Labs. The `sbom export` command allows you to export an SBOM for a specified package from Endor Labs. ## Usage Run the following command to export an SBOM for a specified package version named `go://github.com/Dreamacro/clash@main` in Endor Labs. ```shell theme={null} endorctl sbom export --package-version-name=go://github.com/Dreamacro/clash@main ``` Run the following command to export an SBOM for a specified package version given its UUID with the UUID of `653c625cd44ec559e19349dc` to a file called `sbom.json` ```shell theme={null} endorctl sbom export --package-version-uuid=653c625cd44ec559e19349dc >> sbom.json ``` ## Options # import Source: https://docs.endorlabs.com/developers-api/cli/commands/sbom/import/index Use the SBOM import command to import SBOMs to Endor Labs The `sbom import` command allows you to import SBOMs to Endor Labs to track your third party risk. ## Usage To import an SBOM to Endor Labs use the following command: ```bash theme={null} endorctl sbom import --sbom-file-path=/path/to/your/sbom.json ``` ```bash theme={null} endorctl sbom import --format=spdx --sbom-file-path=/path/to/your/sbom.json ``` ## Options # sbom Source: https://docs.endorlabs.com/developers-api/cli/commands/sbom/index Use the sbom command to import or export SBOMs to or from Endor Labs The `endorctl sbom` command allows you to import or export SBOMs to or from Endor Labs. ## Usage The syntax of `endorctl sbom` is as follows: `endorctl sbom [subcommand] [flags]` The `endorctl sbom` command supports the following subcommands: * `endorctl sbom import` imports an SBOM into Endor Labs. * `endorctl sbom export` allows you to export an SBOM from Endor Labs. ## Options # scan Source: https://docs.endorlabs.com/developers-api/cli/commands/scan/index Use the scan command to perform endorctl scan. Use the `scan` command to perform scans against a repository. ## Usage Run the following command to perform a full scan including reachability analysis for the open source packages you build in a repository. ```bash theme={null} endorctl scan ``` If your project contains multiple programming languages, you can specify them as a comma-separated list using the `--languages` flag: ```bash theme={null} endorctl scan --languages= ``` Provide `` as a comma-separated list using the supported languages: . To scan leaked secrets and monitor all results in the checked out version of your repository. ```bash theme={null} endorctl scan --secrets ``` Run the following command to perform a regular scan for leaked secrets including the dependencies. ```bash theme={null} endorctl scan --secrets --dependencies ``` Run the following command to scan for leaked secrets in all branches of your repository. ```bash theme={null} endorctl scan --secrets --git-logs ``` The above command performs a scan of the repository's Git logs using the following logic: * If endorctl scans the repository's Git log history for the first time, it performs a full scan * endorctl also performs a full rescan if you change any of the rules in the namespace * In all other cases, endorctl runs an incremental scan based on the last scan time If the system invalidates detected secrets and you want to re-validate them, force a full rescan with the following command. To scan for misconfigurations in a GitHub repository like [https://github.com/endorlabs/app-java-demo](https://github.com/endorlabs/app-java-demo). ```bash theme={null} export ENDOR_SCAN_SCM_TOKEN= endorctl scan --github --repository-http-clone-url=https://github.com/endorlabs/app-java-demo ``` To run a scan as a test in a pull request without monitoring the version of your code over time run the command. ```bash theme={null} endorctl scan --pr ``` To scan workflow files under `.github/workflows` and discover Actions used in your pipelines, run the following command. ```bash theme={null} endorctl scan --ghactions ``` For CI integration options including the GitHub App and the Endor Labs GitHub Action, see [GitHub Actions scanning](/scan/github-actions). The command performs regular dependency analysis on your repository. It also discovers GitHub Actions workflows in your CI/CD pipeline and maps them as GitHub action dependencies in your package. To scan binaries and artifacts run the following command. ```bash theme={null} endorctl scan --package --path --project-name ``` You must provide the path of your file using `--path` and specify a name for your project using `--project-name`. To scan and discover AI/LLM models in your repository, run the following command ```bash theme={null} endorctl scan --ai-models --dependencies ``` To run a scan in dry run mode with local scanning and read-only access, run the following command. Dry run mode does not store scan results for monitoring and is best when used by developers running local scans. ```bash theme={null} endorctl scan --dependencies --dry-run ``` You can also use `--dry-run` with `--secrets`, `--sast`, or `--ai-sast` flags. When you use `--dry-run` with `--ai-sast`, you must also set `--diff-scope` to scope the scan to changed files. Do not use `--dry-run` with container scanning. ## Options The command `endorctl scan` uses the following flags and environment variables: ### AI model discovery flags ### Bazel flags ### Pull request (CI) flags ### GitHub configuration flags ### Call graph flags ### Policy flags ### Secrets scan flags ### SAST scan flags The following AI SAST flags are registered with `MarkHidden` — they work but do not appear in `endorctl scan --help`. They are intended for AI SAST rollouts, benchmarking, and advanced use. Confirm with the SME before publishing. ### Sandbox flags ### Miscellaneous flags # artifact sign Source: https://docs.endorlabs.com/developers-api/cli/commands/sign-artifacts/index Use the `artifact sign` command to sign container images and build artifacts in the CI pipeline. Use the `artifact [ sign \| verify ]` command to sign and verify container images and other build artifacts. ## Usage To sign an artifact, use the following command. ```bash theme={null} endorctl artifact sign --name --source-repository-ref --certificate-oidc-issuer ``` To verify a signed artifact, use the following command. ```bash theme={null} endorctl verify --name --certificate-oidc-issuer ` ``` To revoke a signature, use the following command. ```bash theme={null} endorctl artifact revoke-signature --name --source-repository-ref ``` ## Options You can use the following flags and environment variables: For `endorctl artifact sign` For `endorctl artifact verify` For `endorctl artifact [revoke-signature]` # sync-org Source: https://docs.endorlabs.com/developers-api/cli/commands/sync-org/index Use the sync-org command to sync all projects in a GitHub organization to Endor Labs. Use the `endorctl sync-org` command to create projects for all the unscanned repositories in your GitHub organization. This does not automatically scan the projects. It creates projects in Endor Labs, measures scan coverage across a GitHub organization, and gives you visibility into your source control repository. ## Usage To sync your GitHub organization to Endor Labs: * Export a GitHub token that can read all projects in your GitHub organization. To run the sync-org command you need at least `repo` and `read:org permissions`. ```bash theme={null} export GITHUB_TOKEN= ``` * Run the sync-org command. By default, the command skips archived repositories. ```bash theme={null} endorctl sync-org --name=endorlabs ``` The `sync-org` command deletes projects in Endor Labs when you archive their linked repositories on GitHub. Use the `--archived` flag to include archived repositories and prevent Endor Labs from deleting them. ## Options The `endorctl sync-org` command uses the following flags and environment variables: # toolchains Source: https://docs.endorlabs.com/developers-api/cli/commands/toolchains/index Use the toolchains command to detect tools in your repository, create a scan profile, or generate a Dockerfile. Use the `endorctl toolchains` command to detect the current tools used in your repository, create a scan profile, or generate a Dockerfile. Toolchain commands are not supported on Windows. ## Usage * Use the `help` argument to see the options associated with toolchains command. ```bash theme={null} endorctl toolchains --help ``` ### Detect tools in your repository Use `endorctl detect` to identify the tools currently used in your repository. The following arguments can help you refine your scan: * Use the `-p` argument to define the local filesystem path to the repository you want to scan. ```bash theme={null} endorctl toolchains detect -p ``` * Use the `--exclude-path` argument to exclude specific file paths or directories. ```bash theme={null} endorctl toolchains detect -p --exclude-path 'python/**' ``` * Use the `--include-path` argument to limit the scan to a specific file path or directory. ```bash theme={null} endorctl toolchains detect -p --include-path 'development/**' ``` ### Create a scan profile Use `endorctl generate` to create a scan profile. See [Configure build tools](/scan/scan-profiles/build-tools) for more details. * Use the `profile-name` argument to assign a name to your profile. This command creates a `.endorctl/scanprofile.yaml` file with the tools in the repository. ```bash theme={null} endorctl toolchains generate -p --profile-name ``` * Use the `output-type` argument to specify the format of the output file. ```bash theme={null} endorctl toolchains generate -p --profile-name --output-type ``` * Use the `--output-path` argument to set the output file location. ```bash theme={null} endorctl toolchains generate -p --profile-name --output-type json --output-path ``` * Use the `--create-profile` argument to create and save the scan profile using the specified options. ```bash theme={null} endorctl toolchains generate -p --profile-name --create-profile ``` **Detect toolchains in your repository and generate a Dockerfile** Use `endorctl toolchains docker` to auto detect toolchains and build tools in your repository and generate a Dockerfile pre-configured with endorctl and those tools for scanning your project with Endor Labs. This gives you a working scan environment quickly without manually identifying and installing language toolchains. * Navigate to the root of your repository and run the following command to generate a Dockerfile in the current directory. ```bash theme={null} endorctl toolchains docker ``` * Use the `-p` argument to specify the repository path to scan, and the `-o` argument to set where the Dockerfile is written. ```bash theme={null} endorctl toolchains docker -p -o ``` * Use the `-l` or `--languages` argument to limit auto-detection to specific languages. ```bash theme={null} endorctl toolchains docker -p -l -o ``` * Use the `--include-path` argument to limit toolchain auto detection to specific file paths or directories. The following example limits detection to the `development/` directory and its contents. ```bash theme={null} endorctl toolchains docker -p --include-path 'development/**' -o ``` * Use the `--exclude-path` argument to exclude specific paths from toolchain auto detection. The following example excludes the `python/` directory from auto detection. ```bash theme={null} endorctl toolchains docker -p --exclude-path 'python/**' -o ``` ## Options The `endorctl toolchains` command uses the following flags and environment variables. * Flag: `o`, `output-path` Environment\_Variable: `ENDOR_TOOLCHAINS_DOCKER_OUTPUT_PATH` Type: string Description: Set the output path for the generated Dockerfile. Default is `.`. Used with `endorctl toolchains docker`. * Flag: `l`, `languages` Environment\_Variable: `ENDOR_TOOLCHAINS_LANGUAGES` Type: string Description: Limit toolchain auto detection to specific languages. Use with `endorctl toolchains docker`. # ignore Source: https://docs.endorlabs.com/developers-api/cli/commands/validate/ignore/index Validate a yaml ignore file. The `endorctl validate ignore` command validates that an ignore file follows the yaml schema and flags duplicates or invalid entries. ## Usage The syntax of the `endorctl validate ignore` command is: ```bash theme={null} endorctl validate ignore [flags] ``` ### Flags and variables The `endorctl validate ignore` command uses the following flags and environment variables: ### Example usage Validate an ignore file: ```shell theme={null} endorctl validate ignore --path .customignore.yaml ``` ### Example output ```shell theme={null} ERROR invalid-args: Duplicate ignore entry for 'Unmaintained Dependency org.webjars.bowergithub.webcomponents:shadycss@1.9.1': endorlabs/app-java-demo-2 ERROR invalid-args: Duplicate ignore entry for 'Unmaintained Dependency org.webjars.bowergithub.webcomponents:shadycss@1.9.1': endorlabs/app-java-demo-3 An invalid argument was provided. details: 2 errors detected ``` # validate Source: https://docs.endorlabs.com/developers-api/cli/commands/validate/index Use the validate command to validate policies and ignore files The `endorctl validate` command provides validation utilities for policy and ignore files. ## Usage The syntax of `endorctl validate` is: `endorctl validate [command]` The `endorctl validate` command supports the following subcommands: * `endorctl validate ignore` validates ignore file syntax and entries. * `endorctl validate policy` validates policies against project data. # policy Source: https://docs.endorlabs.com/developers-api/cli/commands/validate/policy/index Use this command to validate policies. ## Usage Use the `endorctl validate policy` command to validate one or more policies against data from one or more projects. If the policy is valid, the command returns all matches for the given projects, in the requested format, with the corresponding exit code. The syntax of the `endorctl validate policy` command is: ```bash theme={null} endorctl validate policy [policies] [flags] ``` ### Flags and variables The `endorctl validate policy` command uses the following flags and environment variables: #### Specify one or more policies Use one of the following formats to specify one or more policies: #### Specify a project or a project filter Use one of the following formats to specify one or more projects from which to load data: #### Specify output format As with the other `endorctl` commands, you can specify if you prefer the output as a `table`, or in `json` or `yaml` format. If the output format is `json` or `yaml`, the matching findings appear under `"matching_findings"` and the results for all other resource kinds appear under `"matching_resources"`. For example, `endorctl validate policy --policy-uuid 6418dc7a55afcfb7b0d0e025 --uuid 6699c827cd89accb3a017536 --output-type json`. #### Exit Codes If the policy is valid and there are no matches the command returns 0. The following table lists the non-zero exit codes returned by the `endorctl validate policy` command: For a complete list of endorctl exit codes, see [endorctl CLI exit codes](/best-practices/troubleshooting/endorctl-exitcodes). ### Example Below is an example on how to verify that a Rego policy is correctly formatted. 1. First, define a Rego policy. Let's take the example policy below that searches for dependencies with an Endor Labs overall score of less than 7. You can save this to a file called "test\_policy.rego". ```yaml theme={null} package example match_package_version_score[result] { some i data.resources.Metric[i].meta.name == "package_version_scorecard" data.resources.Metric[i].meta.parent_kind == "PackageVersion" data.resources.Metric[i].meta.parent_uuid == data.resources.PackageVersion[_].uuid score := data.resources.Metric[i].spec.metric_values.scorecard.score_card.overall_score score < 7 result = { "Endor" : { "PackageVersion" : data.resources.Metric[i].meta.parent_uuid }, "Score" : sprintf("%v", [score]) } } ``` 2. Next, validate that the policy is correctly formatted. ```shell theme={null} endorctl validate policy \ --policy test_policy.rego \ --query data.example.match_package_version_score ``` 3. Add a project UUID to validate the policy against real data. ```shell theme={null} endorctl validate policy \ --policy test_policy.rego \ --query data.example.match_package_version_score \ --uuid $PROJECT_UUID \ --output-type json > output.json ``` 4. Inspect the policy output. ```json theme={null} { "matching_resources": { "6553132357b462874261f054": { "Policy 1": { "PackageVersion": [ { "resource_name": "pypi://astunparse@1.6.3", "resource_uuid": "63f599e177cf1f3d7f286ea1", "result": { "None": [ { "Score": "6" } ] } }, ``` ### Troubleshooting * Set `--output-type` to `json` or `yaml` for formatted output * Add the `--verbose` flag for detailed output * Set `--log-level debug` for more information # Global flags and environment variables Source: https://docs.endorlabs.com/developers-api/cli/environment-variables/index Use global flags and environment variables to customize and configure endorctl. Every command-line flag has a corresponding environment variable that you can set instead of the flag, either directly in your environment or in a dedicated configuration file. See `config-path` description in [Global flags](#global-flags) and [Set environment variables](#set-endorctl-environment-variables) for details. To set a command-line flag on the endorctl scan command you can specify the flag with a leading `--` for full flag names or a leading `-` for short flag aliases. If applicable, place input arguments after the flag and separate them with either a blank space or a `=` character. For example, to set the `output-type` specify `--output-type json` or `-o=json`. If the input argument is a list, use a `,` character to separate list elements, for example `--languages=go,python`. ## Global flags The following global flags apply to any `endorctl` command. Each flag has a corresponding environment variable that you can use in place of the flag. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ## Environment variables that affect scan behavior The following environment variables configure scan behavior. They do not have corresponding command-line flags. Set them in your environment, in the scan profile, or in the [config file](#set-endorctl-environment-variables) before running `endorctl`. You can set them in a scan profile with `additional_environment_variables` so they apply automatically to every scan that uses that profile. See [Configure automated scan parameters](/scan/scan-profiles/build-tools#configure-automated-scan-parameters) for details. ## Set `endorctl` environment variables Select your operating system and shell to generate the correct command. # endorctl CLI Source: https://docs.endorlabs.com/developers-api/cli/index Use the command-line interface to scan projects, manage SBOMs, and interact with the API. **endorctl** is a command line utility designed to bring the functionality of Endor Labs into your software delivery workflows. It allows you to scan and monitor your projects, import and export SBOMs, and interact with the API. Learn how to install and configure endorctl. Learn how to use environment variables to configure endorctl. Learn more about the available endorctl commands. # Install and configure endorctl Source: https://docs.endorlabs.com/developers-api/cli/install-and-configure/index Learn how to install, configure, and authenticate with Endor Labs Perform software composition analysis, dependency management, or detect secrets in your code using Endor Labs. ## Download and install endorctl Use one of the following methods to download and install endorctl on your local system. After you install endorctl, you must authenticate. Then you can start scanning your code. ### Install endorctl with Homebrew Use Homebrew to efficiently install endorctl on macOS and Linux operating systems making it easy to manage dependencies, and track installed packages with their versions. Install endorctl from the [Endor Labs tap](https://github.com/endorlabs/homebrew-tap) with Homebrew by running the following commands. Endor Labs updates the tap regularly with the latest endorctl release. ```bash theme={null} brew install endorlabs/tap/endorctl ``` ### Install endorctl with npm Use npm to efficiently install endorctl on macOS, Linux, and Windows operating systems making it easy to manage dependencies, track and update installed packages and their versions. 1. Make sure that you have npm installed in your local environment and use the following command to install endorctl. ```bash theme={null} npm install -g endorctl ``` 2. Run the following command to get the npm global bin directory. ```bash theme={null} npm config get prefix ``` 3. Edit your shell configuration file and insert the path you obtained from the previous command. ```bash theme={null} export PATH="/path/to/npm/global/bin:$PATH" ``` 4. Reload your shell configuration and confirm that endorctl runs. ```bash theme={null} endorctl --version ``` 5. To update your version of endorctl, run the following command. ```bash theme={null} npm update -g endorctl ``` [endorctl](https://www.npmjs.com/package/endorctl) is available as an npm package and Endor Labs updates it regularly with the latest endorctl release. ### Download and install the endorctl binary directly To download the endorctl binary directly use the following commands: ```bash theme={null} # Download the latest CLI for Linux amd64 curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl # Verify the checksum of the binary echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c # Modify the permissions of the binary to ensure it is executable chmod +x ./endorctl # Create an alias endorctl of the binary to ensure it is available in other directory alias endorctl="$PWD/endorctl" ``` ```bash theme={null} # Download the latest CLI for MacOS ARM64 curl https://api.endorlabs.com/download/latest/endorctl_macos_arm64 -o endorctl # Verify the checksum of the binary echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_macos_arm64) endorctl" | shasum -a 256 -c # Modify the permissions of the binary to ensure it is executable chmod +x ./endorctl # Create an alias endorctl of the binary to ensure it is available in other directory alias endorctl="$PWD/endorctl" ``` ```bash theme={null} # Download the latest CLI for Windows amd64 curl -O https://api.endorlabs.com/download/latest/endorctl_windows_amd64.exe # Check the expected checksum of the binary file curl https://api.endorlabs.com/sha/latest/endorctl_windows_amd64.exe # Verify the expected checksum and the actual checksum of the binary match certutil -hashfile .\endorctl_windows_amd64.exe SHA256 # Rename the binary file ren endorctl_windows_amd64.exe endorctl.exe ``` If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. You can also view these instructions via the Endor Labs application user interface: 1. Sign in to Endor Labs. 2. Select **Projects** from the left sidebar. 3. Click **Add Project**. 4. Choose **CLI**. 5. Follow the on-screen instructions to download and install the appropriate version and architecture of `endorctl` for your system. You can keep track of endorctl release details by checking the [Endor Labs release notes](/releasenotes). ### Download a specific version of endorctl To pin your environment to a specific release, download a versioned binary instead of the `latest` URL. To find the latest available version number, run: ```bash theme={null} curl -s https://api.endorlabs.com/meta/version ``` Replace `` with the version string (for example, `v1.6.123`) and download the binary for your platform: ```bash theme={null} curl https://api.endorlabs.com/download/endorlabs//binaries/endorctl__linux_amd64 -o endorctl chmod +x ./endorctl alias endorctl="$PWD/endorctl" ``` ```bash theme={null} curl https://api.endorlabs.com/download/endorlabs//binaries/endorctl__macos_arm64 -o endorctl chmod +x ./endorctl alias endorctl="$PWD/endorctl" ``` ```bash theme={null} curl -O https://api.endorlabs.com/download/endorlabs//binaries/endorctl__windows_amd64.exe ren endorctl__windows_amd64.exe endorctl.exe ``` ## Authenticate to Endor Labs You can authenticate to Endor Labs in the following ways: 1. [Using the init command](#login-with-the-init-command) 2. [With an API token](#login-with-an-api-key) ### Login with the init command Run `endorctl init` and your browser window will open automatically. Select your authentication provider from the available options and complete the authentication process. Init authentication through browser You can also specify your supported authentication provider manually: ```bash theme={null} endorctl init --auth-mode=google ``` ```bash theme={null} endorctl init --auth-mode=github ``` ```bash theme={null} endorctl init --auth-mode=gitlab ``` ```bash theme={null} endorctl init --auth-email=`` ``` ```bash theme={null} endorctl init --auth-mode=sso --auth-tenant=`` ``` To log in with your supported authentication provider in environments without a browser you can use headless mode: ```bash theme={null} endorctl init --auth-mode=google --headless-mode ``` ```bash theme={null} endorctl init --auth-mode=github --headless-mode ``` ```bash theme={null} endorctl init --auth-mode=gitlab --headless-mode ``` ```bash theme={null} endorctl init --auth-email=`` --headless-mode ``` ```bash theme={null} endorctl init --auth-mode=sso --auth-tenant=`` --headless-mode ``` ### Login with an API Key To log in with an API key you'll need to set the following environment variables: * **ENDOR\_API\_CREDENTIALS\_KEY** - The API key used to authenticate against the Endor Labs API. * **ENDOR\_API\_CREDENTIALS\_SECRET** - The API key secret used to authenticate against the Endor Labs API. * **ENDOR\_NAMESPACE** - The Endor Labs namespace you would like to scan against. You can locate the namespace from the top left hand corner of the screen under the Endor Labs logo on the [Endor Labs application](https://app.endorlabs.com). If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. To get an API Key and secret for use with endorctl, see [Managing API Keys](/platform-administration/api-keys). To set your environment variables run the following commands and replace each example with the appropriate value. ```bash theme={null} export ENDOR_API_CREDENTIALS_KEY= export ENDOR_API_CREDENTIALS_SECRET= export ENDOR_NAMESPACE= ``` Once you've exported your environment variables you can test successful authentication by running the following command to list projects in your namespace. ```bash theme={null} endorctl api list -r Project --page-size=1 ``` If you do not have any projects in your namespace you will get an empty json output, which means you are successfully authenticated. ### Print your access token Once you have successfully initialized endorctl, you can print your access token with the following command. ```bash theme={null} endorctl auth --print-access-token ``` The token has an expiration time of 4 hours. ## Persistently set environment variables for endorctl To persistently set an environment variable, append the environment variable and the value to `~/.endorctl/config.yaml`. This configuration file is for CLI usage. For example, if your GitHub Enterprise Server URL was [https://api.github.com](https://api.github.com) you can set the variable to persist in your configuration using the following command. ```bash theme={null} echo "ENDOR_SCAN_SOURCE_GITHUB_API_URL: https://api.github.com" >> ~/.endorctl/config.yaml ``` See [endorctl commands for all supported commands and environment variables](/developers-api/cli/environment-variables). # Developers & API Source: https://docs.endorlabs.com/developers-api/index Programmatically interact with Endor Labs using the REST API, CLI, and MCP Server. Access Endor Labs programmatically through the REST API, command-line interface, or MCP Server for AI-assisted development. Install and use the endorctl command-line interface to run scans and manage your security posture. Use the Endor Labs REST API to query findings, projects, and integrate with your tooling. Integrate Endor Labs into your IDE with the Model Context Protocol for AI-powered development. Use our API query builder to construct endorctl commands based on API operations and parameters. View the complete Endor Labs REST API reference. Learn how to use the API to build your solutions. You can download the Endor Labs REST API specifications directly from the docs site. Each file is served as a static asset. * [openapi.v3.json](https://docs.endorlabs.com/api-reference/openapi.v3.json): Compact OpenAPI 3.x specification that is suitable for most use cases. * [openapi.full.v3.json](https://docs.endorlabs.com/api-reference/openapi.full.v3.json): Full OpenAPI 3.x specification that includes all schemas and operations. * [openapiv2.swagger.json](https://docs.endorlabs.com/api-reference/openapiv2.swagger.json): Full Swagger 2.0 specification for tools that do not yet support OpenAPI 3.x. # About the REST API Source: https://docs.endorlabs.com/developers-api/rest-api/about/index Get oriented with the Endor Labs REST API documentation. ## Introduction You can use the Endor Labs API to build scripts and applications that automate processes, integrate with Endor Labs, and extend Endor Labs. For example, you can use the API to triage findings, build an analytics dashboard, or manage releases. The documentation covers each REST API endpoint individually and groups them by the resource they primarily affect. For example, you can find endpoints relating to findings in [FindingService](/api-reference/findingservice/listfindings). ## Getting started with the REST API If you are new to REST APIs, you may find it helpful to refer to the Quickstart or Getting Started guide for an introduction. For more information, see: * [Quickstart](/developers-api/rest-api/quickstart) * [Getting started](/developers-api/rest-api/using-the-rest-api/getting-started) If you are familiar with REST APIs but new to the Endor Labs REST API, you may find it helpful to refer to the authentication documentation. For more information, see: * [Authentication](/developers-api/rest-api/authentication) ## Further reading * [Best practices](/developers-api/rest-api/using-the-rest-api/best-practices) * [Troubleshooting](/developers-api/rest-api/using-the-rest-api/troubleshooting) # OpenAPI description Source: https://docs.endorlabs.com/developers-api/rest-api/about/open-api/index The Endor Labs REST API is fully described in an OpenAPI compliant document. ## About OpenAPI OpenAPI is a specification for describing REST API interfaces. It describes the API as an open standard to act as a dictionary for an API. OpenAPI enables developers to easily find and discover how to use your API. For more information, see the [OpenAPI specification documentation](https://spec.openapis.org/oas/v3.1.0). ## Using the Endor Labs OpenAPI description Because the OpenAPI description is machine readable, you can use it to do things like: * Generate libraries to facilitate using the REST API * Validate and test an integration that uses the REST API * Explore and interact with the REST API using third-party tools, such as [Postman](https://www.postman.com/downloads/) For example, Endor Labs uses the OpenAPI description to generate the REST API reference documentation for each endpoint. For more information, see the [Endor Labs OpenAPI documentation](/api-reference/). You can download the Endor Labs REST API specifications directly from the docs site. Each file is served as a static asset. * [openapi.v3.json](https://docs.endorlabs.com/api-reference/openapi.v3.json): Compact OpenAPI 3.x specification that is suitable for most use cases. * [openapi.full.v3.json](https://docs.endorlabs.com/api-reference/openapi.full.v3.json): Full OpenAPI 3.x specification that includes all schemas and operations. * [openapiv2.swagger.json](https://docs.endorlabs.com/api-reference/openapiv2.swagger.json): Full Swagger 2.0 specification for tools that do not yet support OpenAPI 3.x. # API Versions Source: https://docs.endorlabs.com/developers-api/rest-api/about/versions/index Learn how to specify which REST API version to use whenever you make a request to the Endor Labs REST API. ## About API versioning The Endor Labs REST API uses explicit versioning. Endor Labs ships breaking changes only in a new API version. New endpoints, fields, and enum values are backwards compatible within the same version. For every new API version that Endor Labs releases, the URL specifies the major version. For example, `https://api.endorlabs.com/v1/namespaces/my_namespace/projects` uses version 1 of the endpoint, per the **v1** path segment. Each resources have their versions specified in the field **meta.version**. For example the following resource has version 1 per the **v1** value for the field **meta.version**. ```json theme={null} { "meta": { "create_time": "2023-12-05T00:04:21.853Z", "kind": "Project", "name": "https://github.com/my_organization/my_repository.git", "update_time": "2024-05-01T16:50:03.830911988Z", "version": "v1" }, "uuid": "656e69058032bf0abaaeb681" } ``` When using the `endorctl` command-line tool to access the API, new endpoints, fields, or enum values are not available if your version of endorctl is older than the API version. Make sure to keep `endorctl` up-to-date to access the latest features and endpoints. For more information, see [Install and configure endorctl](https://docs.endorlabs.com/endorctl/install-and-configure/). ## Check latest API version using curl To check the latest API version using curl, run the following command: ```bash theme={null} curl -s https://api.endorlabs.com/meta/version | jq .ClientVersion ``` ### Example request using curl ```bash theme={null} curl -s https://api.endorlabs.com/meta/version | jq .ClientVersion "v1.6.322" ``` ## Check latest endorctl version To get both the current and the latest version of `endorctl`, run the following command: ```bash theme={null} endorctl --version ``` Along with your current version, you see a notification like the following if a newer `endorctl` version is available. ### Example request using endorctl ```bash theme={null} endorctl --version endorctl version v1.6.293 A newer version of endorctl is available v1.6.317 - currently v1.6.293 ``` # endorctl API Query Builder Source: https://docs.endorlabs.com/developers-api/rest-api/api-query-builder/index Beta
Use our API-based query builder to construct endorctl commands based on actual API operations and parameters. endorctl API is the most user-friendly way to interact with the Endor Labs REST API. It handles authentication automatically, provides built-in error handling with clear messages, and supports multiple output formats including json, yaml, and table. ## Prerequisites Ensure that you complete the following prerequisites before running the commands generated by the API query builder: * Install the latest version of [endorctl](/developers-api/cli/install-and-configure) before running the commands generated by the API query builder. * Run `endorctl init` to authenticate with Endor Labs. See [endorctl init](/developers-api/cli/commands/init) for more information. ## About the API query builder The API query builder allows you to construct [endorctl API](/developers-api/cli/commands/api) commands based on API operations and parameters. The tool currently supports all API operations available in [Top REST API Reference](https://docs.endorlabs.com/top-api/). You can refer to endorctl API command documentation to construct your own queries that are not supported by the API query builder. You can also refer to [Use Cases](/developers-api/rest-api/using-the-rest-api/use-cases) and [Advanced Use Cases](/developers-api/rest-api/using-the-rest-api/advanced-use-cases) to get examples of how you can use endorctl API commands. The tool includes options for timeouts, date filtering, and pagination. It also simplifies complex queries with easy filtering, sorting, and field selection. endorctl also supports grouping queries, which is not currently supported by the API query builder. See [Grouping](/developers-api/rest-api/using-the-rest-api/grouping) for more information. See the [Top REST API Reference](https://docs.endorlabs.com/top-api/) to get the details of request json for the operations that need a json request body. The request body appears in the API query builder for update operations, but you might need to modify it to fit your needs. # Authentication Source: https://docs.endorlabs.com/developers-api/rest-api/authentication/index Learn how to authenticate to the Endor Labs REST API. ## About Authentication Endor Labs supports multiple authentication methods. In all cases, clients use an Endor Labs specific API token to exchange their identity with Endor Labs. The token uses x509 signatures, and the Endor Labs private key signs it. You can initiate the authentication process through the authentication methods described below. The API authenticates the client and returns an Endor Identity Token (`ENDOR_TOKEN`) that it can apply to all its requests. The token validity depends on the authentication providers' [session duration](/platform-administration/rbac/authentication-providers#session-duration). After creating an API token, you can authenticate your requests by including the token in the Authorization header. For example, you can export it using the `ENDOR_TOKEN` variable and then use it in curl commands such as the following. If needed, replace `$ENDOR_NAMESPACE` with the name of your namespace. ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects" \ ``` Basic authentication with curl -u is not supported. The following sections describe the different ways you can create an `ENDOR_TOKEN`. ## Headless mode 1. Paste the following URL in your preferred browser: ```bash theme={null} https://api.endorlabs.com/v1/auth/google?redirect=headless ``` ```bash theme={null} https://api.endorlabs.com/v1/auth/github?redirect=headless ``` ```bash theme={null} https://api.endorlabs.com/v1/auth/gitlab?redirect=headless ``` ```bash theme={null} https://api.endorlabs.com/v1/auth/login?email=&redirect=headless ``` ```bash theme={null} https://api.endorlabs.com/v1/auth/sso?tenant=&redirect=headless ``` 2. Use your browser window to authenticate 3. If authenticating with email, follow the link sent to the provided email 4. Once authenticated, copy the token displayed by the browser 5. Go back to your terminal and export it to your `ENDOR_TOKEN` environment variable ## API key and secret This method provides authentication using Endor Labs API keys. Any user of the system can create an API key under a namespace. The key consists of a key and a secret randomly generated by the system. ### Using endorctl If you [authenticate with Endor Labs using endorctl](/developers-api/cli/commands/init), it creates a `~/.endorctl/config.yaml` file in your environment containing essential details such as the API key, secret, and tenant namespace. Use the following command to export the value of your access token: ```bash theme={null} export ENDOR_TOKEN=$(endorctl auth --print-access-token) ``` ### Using the Endor Labs user interface Generating an API key and secret using the Endor Labs user interface enables you to select a custom expiration date and permissions. To generate an API key and secret via the Endor Labs user interface, follow these steps: 1. Select **User menu** > **Settings** > **Access Control**, then select **API Keys**. 2. Click **Generate API Key**. 3. Specify the following key details: * **Name:** Enter a descriptive name for the API key, identifying its purpose or user. * **Permission Level:** Choose the appropriate permission level for the API key. Options include: * **Admin:** Full access to all features and functionalities. * **Read-only:** View-only access, without the ability to modify or create resources. * **Code Scanner:** Access specifically for code scanning functionalities. * **Policy Editor:** Access to policy editing features. * **On-Prem Scheduler:** Access to manage [Outpost](/setup-deployment/outpost) and to use [monitoring scans](/setup-deployment/scm-integrations) across supported platforms when you enable Outpost. * **Package Firewall User:** Access to authenticate to the [Package Firewall](/package-firewall) and route package installation traffic through it. * **AI Audit User:** Access to submit agent session events and read the active policy snapshot for [Coding Agent Governance](/agent-governance) hooks on developer machines. 4. Select the desired expiry date for the API key, ranging from 30 to 90 days. 5. Click **Generate API Key** for confirmation. Under the **Advanced** section, you have the option to propagate the API key to all child namespaces. After generating your API key and secret, click **Copy API Key & Secret**. Make sure to securely store your API secret in a safe location, as it will not be accessible through the Endor Labs user interface later. The copied key and secret will look like this: ```bash theme={null} # Endor API Key: name # Expires: 2024-09-05T00:06:16.789Z ENDOR_API_CREDENTIALS_KEY=endr+foo ENDOR_API_CREDENTIALS_SECRET=endr+bar ``` You can then get a token by making a `POST` request with the API key and secret to the `https://api.endorlabs.com/v1/auth/api-key` endpoint. The response contains both the token and the expiration time, so use `jq` to extract the token and export it directly to the `ENDOR_TOKEN` environment variable. ```bash theme={null} export ENDOR_TOKEN=$(curl --request POST \ --url "https://api.endorlabs.com/v1/auth/api-key" \ --data "{ \"key\": \"$ENDOR_API_CREDENTIALS_KEY\", \"secret\": \"$ENDOR_API_CREDENTIALS_SECRET\" }" \ | jq -r .token) ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com ### POST {{baseUrl}}/v1/auth/api-key content-type: application/json { "key" : "endr+foo", "secret":"endr+bar" } ``` ## Authentication precedence If you have set up multiple ways to authenticate endorctl, the precedence is as follows: 1. **Arguments in the endorctl command** You can provide [authentication information in the endorctl command](/developers-api/cli/commands/init), and these credentials take the highest precedence during authentication. Even if authentication information is available in the `~/.endorctl/config.yaml` file or the `ENDOR_TOKEN` environment variable, the value you provide in the command takes precedence. 2. **Authentication information in `~/.endorctl/config.yaml`** If you [authenticate with Endor Labs using endorctl](/developers-api/cli/commands/init), the `~/.endorctl/config.yaml` file is created in your environment that contains authentication information (such as API key and tenant namespace). Even if you set a different authentication token as the `ENDOR_TOKEN` environment variable, the information in the `~/.endorctl/config.yaml` file takes precedence. 3. **ENDOR\_TOKEN environment variable** If you do not provide authentication information in the endorctl command or if there is no authentication information in the `~/.endorctl/config.yaml` file, the authentication information specified in the `ENDOR_TOKEN` environment variable is used for authentication. To use the `ENDOR_TOKEN` variable, ensure that neither the command-line arguments nor the `~/.endorctl/config.yaml` file contain authentication information. ## Failed authentication If you try to use a REST API endpoint without an Endor Labs token, you will receive a 401 Unauthorized response. For more information, see [troubleshooting](/developers-api/rest-api/using-the-rest-api/troubleshooting). # REST API changelog Source: https://docs.endorlabs.com/developers-api/rest-api/changelog/index Version-by-version changes to the Endor Labs REST API. The Endor Labs REST API uses explicit versioning. Endor Labs ships breaking changes only in a new API version. New endpoints, fields, and enum values are backwards compatible within the same version. For more information, see [API versions](/developers-api/rest-api/about/versions). No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. The following updates have been made to the Endor Labs REST API as part of this release. Added the following endpoints. No changes to public-facing endpoints or services in this release. The following updates have been made to the Endor Labs REST API as part of this release. Added the enum value `PACKAGE_FIREWALL_ACTION_CURATED` at the following locations. Added the enum value `PACKAGE_FIREWALL_REASON_VERSIONS_CURATED` at the following locations. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. The following updates have been made to the Endor Labs REST API as part of this release. Added the enum value `TYPE_FINDING_REFRESH` at the following locations. The following updates have been made to the Endor Labs REST API as part of this release. Added the enum value `ENDORCTL_RC_SCAN_CANCELLED` at the following locations. No changes to public-facing endpoints or services in this release. The following updates have been made to the Endor Labs REST API as part of this release. Added the enum value `ACTION_TYPE_ADO_BOARDS` at the following locations. The following updates have been made to the Endor Labs REST API as part of this release. Added the enum value `ENDORCTL_RC_BASELINE_NOT_FOUND` at the following locations. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. The following updates have been made to the Endor Labs REST API as part of this release. Added the following endpoints. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. The following updates have been made to the Endor Labs REST API as part of this release. Added the enum value `FINDING_TAGS_SEGMENT_MATCH` at the following locations. The following updates have been made to the Endor Labs REST API as part of this release. Added the enum value `SYSTEM_ROLE_AI_AUDIT` at the following locations. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. No changes to public-facing endpoints or services in this release. The following updates have been made to the Endor Labs REST API as part of this release. Added the following endpoints. No changes to public-facing endpoints or services in this release. The following updates have been made to the Endor Labs REST API as part of this release. Added the enum value `MALWARE_SOURCE_INTERNAL` at the following locations. The following updates have been made to the Endor Labs REST API as part of this release. Added the enum value `ENDORCTL_RC_DEPENDENCY_SETUP_WARNING` at the following locations. No changes to public-facing endpoints or services in this release. The following updates have been made to the Endor Labs REST API as part of this release. Added the following endpoints. The following updates have been made to the Endor Labs REST API as part of this release. Added the following endpoints. Added the enum value `AGGREGATION_TYPE_MANUAL` at the following locations. # REST API Source: https://docs.endorlabs.com/developers-api/rest-api/index Create integrations, retrieve data, and automate your workflows with the Endor Labs REST API. Get oriented with the Endor Labs REST API documentation. Learn how to use the API to build your solutions. Learn how to authenticate to the Endor Labs REST API. Use our API query builder to construct endorctl commands based on API operations and parameters. Explore use cases with Endor Labs REST API. Learn about the Endor Labs data model. Best practices when using the Endor Labs REST API. Diagnose and resolve issues with the Endor Labs REST API. View the complete Endor Labs REST API reference. You can download the Endor Labs REST API specifications directly from the docs site. Each file is served as a static asset. * [openapi.v3.json](https://docs.endorlabs.com/api-reference/openapi.v3.json): Compact OpenAPI 3.x specification that is suitable for most use cases. * [openapi.full.v3.json](https://docs.endorlabs.com/api-reference/openapi.full.v3.json): Full OpenAPI 3.x specification that includes all schemas and operations. * [openapiv2.swagger.json](https://docs.endorlabs.com/api-reference/openapiv2.swagger.json): Full Swagger 2.0 specification for tools that do not yet support OpenAPI 3.x. # Quickstart Source: https://docs.endorlabs.com/developers-api/rest-api/quickstart/index Start using the Endor Labs REST API immediately. This article describes how to quickly get started with the Endor Labs REST API using the Endor Labs command line tool `endorctl` or `curl`. For a more detailed guide, see [Getting started with the REST API](/developers-api/rest-api/using-the-rest-api/getting-started). The following is an example request to get the number of findings in your namespace: 1. Run `endorctl init` and your browser window will open automatically. Select your authentication provider from the available options and complete the authentication process. You can also specify your supported authentication provider manually. ```bash theme={null} endorctl init --auth-mode google ``` 2. Use the `endorctl` command-line tool to make your request. Note that you do not have to provide the namespace or access token when using `endorctl` to access the Endor Labs REST API. For more information, see the [Endor Labs CLI documentation](/developers-api/cli/commands/api). ```bash theme={null} endorctl api list -r Finding --count ``` 1. Install `curl` if it isn't already installed on your machine. To check if `curl` is installed, execute `curl --version` on the command line. If the output provides information about the version of `curl`, that means `curl` is installed. If you get a message similar to command not found: curl, you need to download and install curl. For more information, see the [curl project download page](https://curl.se/download.html). 2. Run `endorctl init` and your browser window will open automatically. Select your authentication provider from the available options and complete the authentication process. You can also specify your supported authentication provider manually. ```bash theme={null} endorctl init --auth-mode google ``` 3. Create an access token. The access token produced below has the same scopes/permissions as the API key created through `endorctl init`. **Treat your access token like a password**. For more information, see [Authentication](/developers-api/rest-api/authentication). ```bash theme={null} export ENDOR_TOKEN=$(endorctl auth --print-access-token) ``` 4. Use the Curl command to make your request. Pass your token in an Authorization header. The following is an example request to get the number of findings in a given namespace. If needed, replace `$ENDOR_NAMESPACE` with the name of your namespace, or export it as a variable using `export ENDOR_NAMESPACE=`. ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.count=true" ``` For more information on HTTP headers and parameters, see [Getting Started](/developers-api/rest-api/using-the-rest-api/getting-started). For more examples of common use cases, see [Use cases](/developers-api/rest-api/using-the-rest-api/use-cases). # Using Audit Log API Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/advanced-use-cases/audit-log/index Learn how to use the audit log API in Endor Labs Audit logs help to monitor user actions and system operations, and generate audit trails for compliance requirements. You can use the [list AuditLog endpoint](/api-reference/auditlogservice/listauditlogs) to retrieve audit logs. You can retrieve audit logs for the following resources: * Tenants and namespaces * Projects * Users and user telemetry * Repositories and repository versions * Scan results * Authorization policies * Action policies * Remediation policies * Notification policies * Supported toolchains * Application telemetry * Endor Labs licenses Run the following command to fetch the entire audit log. ```bash theme={null} endorctl api list -r AuditLog -n ``` ### Audit log retention and archival Audit logs remain in the active database for 30 days before being automatically moved to archive storage, where they're retained for 3 years. Both active and archived logs support the same filters, pagination, and field masks. You can access archived logs older than 30 days using either of the following methods: 1. Using the `endorctl` command with the `--archive` flag: ```bash theme={null} endorctl api list -r AuditLog -n --archive ``` 2. Using a direct API request: ```bash theme={null} curl -X GET "https://api.endorlabs.com/v1/namespaces//audit-logs/archived" \ -H "Authorization: Bearer ${ENDOR_API_KEY}" \ -H "Content-Type: application/json" ``` Query audit logs from the last 30 days and archived logs separately. ## Operations with the audit log API You can pass the [`meta`](#meta-fields) and [`spec`](#spec-fields) fields with the `endorctl list AuditLog` command to refine the output based on your requirements. You can combine multiple filters in the same command and use multiple operators. See [Filters](/developers-api/rest-api/using-the-rest-api/filters) for more information on using filters and operators. The `meta` and `spec` options listed are not exhaustive. You can build your command based on the `meta` and `spec` fields in the [API specification](/api-reference/auditlogservice/listauditlogs). When retrieving archived audit logs, filter by `spec.message_kind` first, followed by `meta.create_time` for optimal query performance. Always pair the `meta.create_time` filter with `spec.message_kind`. ## Operators You can use the following operators with the filters. ### Meta fields You can use the following `meta` fields. ### Spec fields ### Timeout in AuditLog API Since querying audit logs might take more time in comparison with other API operations, you may face a timeout with the error message, `ERROR deadline-exceeded: context deadline exceeded`. If you face the error, provide a timeout override along with your API command to complete the API call. You can use the `--timeout` option and provide the override in seconds: `endorctl api --timeout=s`. For example, `endorctl api list -r AuthenticationLog --timeout=30s`. The default timeout is 20 seconds. ## Examples of using AuditLog API The following sections provide example scenarios for using the audit log API. ### Filter audit log by time range Audit logs grow over time. Restrict the date range to retrieve meaningful data for a specific timeframe. The following example retrieves the audit log for January 2025. ```bash theme={null} endorctl api list -r AuditLog -n demo \ --filter="meta.create_time>=date(2025-01-01T00:00:00Z) and meta.create_time<=date(2025-01-31T23:59:59Z)" ``` ### Filter audit log by users and time range You can retrieve logs for a specific user within a date range. The following example retrieves the audit log of a user with the name `Doe` in their claims token. ```bash theme={null} endorctl api list -r AuditLog -n demo \ --filter="meta.create_time>=date(2025-02-01T00:00:00Z) and meta.create_time<=date(2025-02-19T23:59:59Z) and spec.claims matches '.*firstname=Doe.*'" ``` The following example retrieves the audit log of all users with `endor.ai` as the domain in their claims token. ```bash theme={null} endorctl api list -r AuditLog -n demo \ --filter="meta.create_time>=date(2025-02-01T00:00:00Z) and meta.create_time<=date(2025-02-19T23:59:59Z) and spec.claims matches '.*domain=endor.ai.*'" ``` ### Filter audit log based on operation types You can retrieve the specific audit logs based on a particular operation. The following retrieves audit logs that pertain to create operation after August 18, 2024. ```bash theme={null} endorctl api list -r AuditLog -n demo \ --filter="spec.operation=='OPERATION_CREATE' and meta.create_time>=date(2024-08-18T00:00:00Z)" ``` ### Filter audit log based on message type You can retrieve audit logs based on the message type. You need to provide `internal.endor.ai.endor.v1.` followed by the message type with the `spec.message_kind` filter. The following example retrieves updates to scan results. ```bash theme={null} endorctl api list -r AuditLog -n demo \ --filter="spec.operation=='OPERATION_CREATE' and spec.message_kind=='internal.endor.ai.endor.v1.ScanResult'" ``` ### Filter audit log based on policy updates You can retrieve audit logs for the updates on policies. The following example retrieves updates to action, notification, and remediation policies made after August 18, 2024. ```bash theme={null} endorctl api list -r AuditLog -n demo \ --filter="spec.operation=='OPERATION_CREATE' and spec.message_kind=='internal.endor.ai.endor.v1.Policy' and meta.create_time>=date(2024-08-18T00:00:00Z)" ``` The following example retrieves changes to authorization policies made after August 18, 2024. ```bash theme={null} endorctl api list -r AuditLog -n demo \ --filter="spec.operation=='OPERATION_UPDATE' and spec.message_kind=='internal.endor.ai.endor.v1.AuthorizationPolicy' and meta.create_time>=date(2024-08-18T00:00:00Z)" ``` ### Filter audit log based on IP range You can retrieve audit logs based on an IP range to investigate activities originating from a particular geography or a particular service that uses your Endor Labs instance. The following example retrieves audit log for activities done from the IP range, `10.244.0.0` to `10.244.255.255`. ```bash theme={null} endorctl api list -r AuditLog -n demo \ --filter="spec.remote_address>='10.244.0.0' and spec.remote_address<='10.244.255.255'" ``` ### Retrieve the history of an object based on message UUID You can retrieve the history of an object based on the message UUID. ```bash theme={null} endorctl api list -r AuditLog -n demo \ --filter="spec.message_uuid==''" ``` The following example retrieves the history of an action policy with the UUID, `66axxxxxxxxxx4c15dc1`. ```bash theme={null} endorctl api list -r AuditLog -n demo \ --filter="spec.message_uuid=='66axxxxxxxxxx4c15dc1'" ``` # Advanced use cases Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/advanced-use-cases/index Examples of advanced use cases when interacting with the Endor Labs REST API. Learn how to use the Query Service for advanced use cases with the Endor Labs REST API. Learn how to use saved queries for interacting with the Endor Labs REST API. Learn how to use the audit log API in Endor Labs. # Using the query service Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/advanced-use-cases/query-service/index Learn how to use the Query Service for advanced use cases with the Endor Labs REST API. Beyond REST API endpoints for individual [Resource Kinds](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds), the Endor Labs REST API exposes a generic graph API through the [Query Service](/api-reference/queryservice/createquery) endpoint. Use the Query Service to retrieve resources and their related resources in a single call. Send resource requests through the Query Service with a Query that specifies a [Resource Kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds) and optional [list parameters](/developers-api/rest-api/using-the-rest-api/getting-started#list-parameters) to control the returned data. The Query may also specify nested references, connecting related [Resource Kinds](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#introduction), and returning all corresponding data in the response. ## List projects with package version counts The following Query returns the number of package versions in the default branch of each project. 1. Request a list of projects, but only return the `uuid`, `meta.name` and `processing_status` fields for each project. 2. Connect the project `uuid` to the corresponding child package version `spec.project_uuid` field. 3. Set additional parameters to filter to only resources from the project's default branch, and to return the count of resources.© ```bash theme={null} endorctl api create --resource Query \ --data '{ "meta": { "name": "Projects with Package Version Counts" }, "spec": { "query_spec": { "kind": "Project", "list_parameters": { "mask": "uuid,meta.name,processing_status" }, "references": [ { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "kind": "PackageVersion", "list_parameters": { "filter": "context.type==CONTEXT_TYPE_MAIN", "count": true } } } ] } } }' ``` ```bash theme={null} query_data=$(cat << EOF { "meta": { "name": "Projects with Package Version Counts" }, "spec": { "query_spec": { "kind": "Project", "list_parameters": { "mask": "uuid,meta.name,processing_status" }, "references": [ { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "kind": "PackageVersion", "list_parameters": { "filter": "context.type==CONTEXT_TYPE_MAIN", "count": true } } } ] } }, "tenant_meta": { "namespace": "$ENDOR_NAMESPACE" } } EOF ) curl "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/queries" \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --request POST \ --data "$query_data" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` ### POST {{baseUrl}}/v1/namespaces/{{namespace}}/queries HTTP/1.1 Authorization: Bearer {{token}} { "meta": { "name": "Projects with Package Version Counts" }, "spec": { "query_spec": { "kind": "Project", "list_parameters": { "mask": "uuid,meta.name,processing_status" }, "references": [ { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "kind": "PackageVersion", "list_parameters": { "filter": "context.type==CONTEXT_TYPE_MAIN", "count": true } } } ] } }, "tenant_meta": { "namespace": "{{namespace}}" } } ``` The response includes the original query request along with the list response data under the `spec.query_response` field. For each project in the list response, each reference's data appears under the `meta.references` field. ```json expandable theme={null} { "meta": { "name": "Projects with Package Version Counts" }, "spec": { "query_spec": { "kind": "Project", "list_parameters": { "mask": "uuid,meta.name,processing_status" } }, "query_response": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListProjectsResponse", "list": { "objects": [ { "meta": { "name": "https://github.com/example/app.git", "references": { "PackageVersion": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListPackageVersionsResponse", "count_response": { "count": 12 } } } }, "processing_status": { "analytic_time": "2023-10-28T03:41:40.824366382Z", "disable_automated_scan": false, "scan_state": "SCAN_STATE_IDLE", "scan_time": "2024-06-03T17:43:33.994191285Z" }, "uuid": "633cbce48c4eb448a44d717b" }, { "meta": { "name": "https://github.com/example/go-uuid.git", "references": { "PackageVersion": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListPackageVersionsResponse", "count_response": { "count": 8 } } } }, "processing_status": { "analytic_time": "2023-06-21T02:06:43.081498151Z", "disable_automated_scan": false, "scan_state": "SCAN_STATE_IDLE", "scan_time": "2024-06-03T17:43:47.098976874Z" }, "uuid": "633cbce48c4eb448a44d717e" }, { "meta": { "name": "https://github.com/example/go-lru.git", "references": { "PackageVersion": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListPackageVersionsResponse", "count_response": { "count": 28 } } } }, "processing_status": { "analytic_time": "2023-06-21T02:08:44.727640782Z", "disable_automated_scan": false, "scan_state": "SCAN_STATE_IDLE", "scan_time": "2024-06-03T17:43:52.028934453Z" }, "uuid": "633cbce48c4eb448a44d7181" } ], "response": { "next_page_token": null } } } } } ``` ## List projects, with repository versions and CI/CD tool metrics The following query requests a list of projects, with a reference for the related RepositoryVersion resources for the default branch, and the corresponding CI/CD tool Metric resources. 1. Request a list of projects, but only return the `uuid` and `meta.name` fields for each project. 2. Connect the project `uuid` to the corresponding child RepositoryVersion `meta.parent_uuid` field. 3. Set additional parameters to filter to only resources from the project's default branch, and an additional nested reference for Metric objects related to the RepositoryVersions, with a filter to return only Metrics for the CI/CD tools. ```bash theme={null} endorctl api create --resource Query \ --data '{ "meta": { "name": "Projects with RepositoryVersions and CI/CD Tool Metrics" }, "spec": { "query_spec": { "kind": "Project", "list_parameters": { "mask": "uuid,meta.name" }, "references": [ { "connect_from": "uuid", "connect_to": "meta.parent_uuid", "query_spec": { "kind": "RepositoryVersion", "list_parameters": { "filter": "context.type==CONTEXT_TYPE_MAIN", "mask": "uuid,meta.name,scan_object" }, "references": [ { "connect_from": "uuid", "connect_to": "meta.parent_uuid", "query_spec": { "kind": "Metric", "list_parameters": { "filter": "spec.analytic==\"version_cicd_tools\"" } } } ] } } ] } } }' ``` ```bash theme={null} query_data=$(cat << EOF { "meta": { "name": "Projects with RepositoryVersions and CI/CD Tool Metrics" }, "spec": { "query_spec": { "kind": "Project", "list_parameters": { "mask": "uuid,meta.name" }, "references": [ { "connect_from": "uuid", "connect_to": "meta.parent_uuid", "query_spec": { "kind": "RepositoryVersion", "list_parameters": { "filter": "context.type==CONTEXT_TYPE_MAIN", "mask": "uuid,meta.name,scan_object" }, "references": [ { "connect_from": "uuid", "connect_to": "meta.parent_uuid", "query_spec": { "kind": "Metric", "list_parameters": { "filter": "spec.analytic==\"version_cicd_tools\"" } } } ] } } ] } }, "tenant_meta": { "namespace": "$ENDOR_NAMESPACE" } } EOF ) curl "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/queries" \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --request POST \ --data "$query_data" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` ### POST {{baseUrl}}/v1/namespaces/{{namespace}}/queries HTTP/1.1 Authorization: Bearer {{token}} { "meta": { "name": "Projects with RepositoryVersions and CI/CD Tool Metrics" }, "spec": { "query_spec": { "kind": "Project", "list_parameters": { "mask": "uuid,meta.name" }, "references": [ { "connect_from": "uuid", "connect_to": "meta.parent_uuid", "query_spec": { "kind": "RepositoryVersion", "list_parameters": { "filter": "context.type==CONTEXT_TYPE_MAIN", "mask": "uuid,meta.name,scan_object" }, "references": [ { "connect_from": "uuid", "connect_to": "meta.parent_uuid", "query_spec": { "kind": "Metric", "list_parameters": { "filter": "spec.analytic==\"version_cicd_tools\"" } } } ] } } ] } }, "tenant_meta": { "namespace": "{{namespace}}" } } ``` The response for the example above includes then related repository versions and metrics as nested references under their parent resources. ```json expandable theme={null} { "meta": { "name": "Projects with RepositoryVersions and CI/CD Tool Metrics" }, "spec": { "query_response": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListProjectsResponse", "list": { "objects": [ { "meta": { "name": "https://github.com/OWASP-Benchmark/BenchmarkJava.git", "references": { "RepositoryVersion": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListRepositoryVersionsResponse", "list": { "objects": [ { "meta": { "name": "master", "references": { "Metric": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListMetricsResponse", "list": { "objects": [ { "spec": { "analytic": "version_cicd_tools", "metric_values": { "CiCdTools": { "category": "CiCdTools", "ci_cd_tools": { "tools": [ // additional content from response not shown here ] } } } }, "uuid": "65b0287557d245d7a840220d" } ], "response": {} } } } }, "scan_object": { "scan_time": "2024-04-15T02:17:56.541640347Z", "status": "STATUS_SCANNED" }, "uuid": "65b02837f82e0aeecbf468df" } ], "response": {} } } } }, "uuid": "65b028374ab228de2903786e" } ], "response": {} } }, // additional content from response not shown here } ``` ## Find a project and related Finding counts The following query example requests the projects matching the given filter, with multiple references specified for the counts of related finding resources for the default branch. > Note: When using multiple references of the same resource kind, the field `return_as` serves as the key for identifying references in the response. ```bash theme={null} endorctl api create --resource Query \ --data '{ "meta": { "name": "Project with Finding counts by category" }, "spec": { "query_spec": { "kind": "Project", "list_parameters": { "filter": "meta.name matches \"acme-monorepo\"", "mask": "uuid,meta.name" }, "references": [ { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "return_as": "VulnerabilityFindingsCount", "kind": "Finding", "list_parameters": { "count": true, "filter": "context.type==CONTEXT_TYPE_MAIN and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]" } } }, { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "return_as": "SecretsFindingsCount", "kind": "Finding", "list_parameters": { "count": true, "filter": "context.type==CONTEXT_TYPE_MAIN and spec.finding_categories contains [FINDING_CATEGORY_SECRETS]" } } }, { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "return_as": "MalwareFindingsCount", "kind": "Finding", "list_parameters": { "count": true, "filter": "context.type==CONTEXT_TYPE_MAIN and spec.finding_categories contains [FINDING_CATEGORY_MALWARE]" } } } ] } } }' ``` ```bash theme={null} query_data=$(cat << EOF { "meta": { "name": "Project with Finding counts by category" }, "spec": { "query_spec": { "kind": "Project", "list_parameters": { "filter": "meta.name matches \"acme-monorepo\"", "mask": "uuid,meta.name" }, "references": [ { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "return_as": "VulnerabilityFindingsCount", "kind": "Finding", "list_parameters": { "count": true, "filter": "context.type==CONTEXT_TYPE_MAIN and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]" } } }, { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "return_as": "SecretsFindingsCount", "kind": "Finding", "list_parameters": { "count": true, "filter": "context.type==CONTEXT_TYPE_MAIN and spec.finding_categories contains [FINDING_CATEGORY_SECRETS]" } } }, { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "return_as": "MalwareFindingsCount", "kind": "Finding", "list_parameters": { "count": true, "filter": "context.type==CONTEXT_TYPE_MAIN and spec.finding_categories contains [FINDING_CATEGORY_MALWARE]" } } } ] } }, "tenant_meta": { "namespace": "$ENDOR_NAMESPACE" } } EOF ) curl "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/queries" \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --request POST \ --data "$query_data" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` ### POST {{baseUrl}}/v1/namespaces/{{namespace}}/queries HTTP/1.1 Authorization: Bearer {{token}} { "meta": { "name": "Project with Finding counts by category" }, "spec": { "query_spec": { "kind": "Project", "list_parameters": { "filter": "meta.name matches \"acme-monorepo\"", "mask": "uuid,meta.name" }, "references": [ { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "return_as": "VulnerabilityFindingsCount", "kind": "Finding", "list_parameters": { "count": true, "filter": "context.type==CONTEXT_TYPE_MAIN and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]" } } }, { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "return_as": "SecretsFindingsCount", "kind": "Finding", "list_parameters": { "count": true, "filter": "context.type==CONTEXT_TYPE_MAIN and spec.finding_categories contains [FINDING_CATEGORY_SECRETS]" } } }, { "connect_from": "uuid", "connect_to": "spec.project_uuid", "query_spec": { "return_as": "MalwareFindingsCount", "kind": "Finding", "list_parameters": { "count": true, "filter": "context.type==CONTEXT_TYPE_MAIN and spec.finding_categories contains [FINDING_CATEGORY_MALWARE]" } } } ] } }, "tenant_meta": { "namespace": "{{namespace}}" } } ``` The response for the above example includes the Finding counts as references on the project list response, using the values provided with `return_as` for the reference keys. ```json expandable theme={null} { "meta": { "name": "Project with Finding counts by category" }, "spec": { "query_response": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListProjectsResponse", "list": { "objects": [ { "meta": { "name": "https://github.com/example/acme-monorepo.git", "references": { "MalwareFindingsCount": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListFindingsResponse", "count_response": { "count": 1 } }, "SecretsFindingsCount": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListFindingsResponse", "count_response": { "count": 8 } }, "VulnerabilityFindingsCount": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListFindingsResponse", "count_response": { "count": 74 } } } }, "uuid": "65bbde52d70a7f64c70de4d6" } ], "response": {} } }, // additional content from response not shown here } ``` ## Pagination in Query Service endpoint The `page_size` field allows you to control the number of elements returned. By default, this value is 100, with a maximum of 500. A paginated response includes a value for the field, `next_page_token`. You can use this value to fetch additional pages of results. For example, the following query requests for vulnerability findings. ```bash expandable theme={null} endorctl api create --resource Query \ --data '{ "tenant_meta": { "namespace": "doe" }, "spec": { "query_spec": { "kind": "Finding", "list_parameters": { "page_size": 50, "filter": "meta.name == \'vulnerability\'" } } } }' ``` The response to the request contains `next_page_token`. ```json expandable theme={null} { "spec": { "query_response": { "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListFindingsResponse", "list": { "objects": [ { "meta": { "name": "vulnerability", "description": "Example vulnerability finding" }, "spec": { "level": "FINDING_LEVEL_CRITICAL", "finding_categories": ["FINDING_CATEGORY_VULNERABILITY"] } } // Additional findings up to page_size of 50 ], "response": { "next_page_token": 50, "next_page_id": "unique-id-for-next-page" } } } } } ``` Send the next request with the `next_page_token` to fetch the next set of results. ```bash expandable theme={null} endorctl api create --resource Query \ --data '{ "tenant_meta": { "namespace": "doe" }, "spec": { "query_spec": { "kind": "Finding", "list_parameters": { "page_size": 50, "page_token": 50, "filter": "meta.name == \'vulnerability\'" } } } }' ``` # Using saved queries Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/advanced-use-cases/saved-queries/index Learn how to use saved queries for interacting with the Endor Labs REST API. The Endor Labs REST API provides the [Query Service](/api-reference/queryservice/createquery) for flexible requests for resources. The Endor Labs REST API also provides the ability to save and manage queries for your own use cases through the [Saved Query Service](/api-reference/savedqueryservice/listsavedqueries). See [Using the Query Service](/developers-api/rest-api/using-the-rest-api/advanced-use-cases/query-service) for examples on using the Query Service to specify and request resources from the Endor Labs REST API. ## Creating a saved query To create a saved query, embed a Query object specifying the request in a SavedQuery object. ```bash theme={null} saved_query_data=$(cat << EOF { "meta": { "name": "Saved Query for Recent Vulnerabilities" }, "spec": { "query": { "meta": { "name": "Query for Recent Vulnerabilities" }, "spec": { "query_spec": { "kind": "Finding", "list_parameters": { "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]", "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level" } } }, "tenant_meta": { "namespace": "$ENDOR_NAMESPACE" } } } } EOF ) endorctl api create --resource SavedQuery \ --data "$saved_query_data" ``` ```bash theme={null} saved_query_data=$(cat << EOF { "meta": { "name": "Saved Query for Recent Vulnerabilities" }, "spec": { "query": { "meta": { "name": "Query for Recent Vulnerabilities" }, "spec": { "query_spec": { "kind": "Finding", "list_parameters": { "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]", "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level" } } }, "tenant_meta": { "namespace": "$ENDOR_NAMESPACE" } } }, "tenant_meta": { "namespace": "$ENDOR_NAMESPACE" } } EOF ) curl "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/saved-queries" \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --request POST \ --data "$saved_query_data" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` ### POST {{baseUrl}}/v1/namespaces/{{namespace}}/saved-queries HTTP/1.1 Authorization: Bearer {{token}} { "meta": { "name": "Saved Query for Recent Vulnerabilities" }, "spec": { "query": { "meta": { "name": "Query for Recent Vulnerabilities" }, "spec": { "query_spec": { "kind": "Finding", "list_parameters": { "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]", "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level" } } }, "tenant_meta": { "namespace": "{{namespace}}" } } }, "tenant_meta": { "namespace": "{{namespace}}" } } ``` ## Updating a saved query The following example updates the Query specified in the SavedQuery to add additional [list parameters](/developers-api/rest-api/using-the-rest-api/getting-started#list-parameters). ```bash theme={null} saved_query_uuid="``" saved_query_data=$(cat << EOF { "spec": { "query": { "spec": { "query_spec": { "kind": "Finding", "list_parameters": { "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]", "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level", "page_size": 10, "sort": { "order": "SORT_ENTRY_ORDER_DESC", "path": "meta.create_time" } } } } } } } EOF ) endorctl api update --resource SavedQuery \ --uuid "$saved_query_uuid" \ --field-mask "spec.query.spec.query_spec" \ --data "$saved_query_data" ``` ```bash theme={null} saved_query_uuid="``" saved_query_data=$(cat << EOF { "request": { "update_mask": "spec.query.spec.query_spec" }, "object": { "uuid": "$saved_query_uuid", "spec": { "query": { "spec": { "query_spec": { "kind": "Finding", "list_parameters": { "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]", "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level", "page_size": 10, "sort": { "order": "SORT_ENTRY_ORDER_DESC", "path": "meta.create_time" } } } } } } } } EOF ) curl "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/saved-queries" \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --request PATCH \ --data "$saved_query_data" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` @uuid = `` ### PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/saved-queries HTTP/1.1 Authorization: Bearer {{token}} { "request": { "update_mask": "spec.query.spec.query_spec" }, "object": { "uuid": "{{uuid}}", "spec": { "query": { "spec": { "query_spec": { "kind": "Finding", "list_parameters": { "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]", "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level", "page_size": 10, "sort": { "order": "SORT_ENTRY_ORDER_DESC", "path": "meta.create_time" } } } } } } } } ``` See also [interactive mode](/developers-api/cli/commands/api#endorctl-api-update-interactive-mode) for managing updates to a SavedQuery with `endorctl api update`: ```bash theme={null} endorctl api update --interactive --resource SavedQuery \ --name "Saved Query for Recent Vulnerabilities" ``` ## Evaluating saved queries After you create a Saved Query, you can evaluate the request specified by its Query on demand. ```bash theme={null} endorctl api get --resource SavedQuery --uuid `` ``` ```bash theme={null} base_url="https://api.endorlabs.com" uuid="``" curl "$base_url/v1/namespaces/$ENDOR_NAMESPACE/saved-queries/$uuid/evaluate" \ --header "Authorization: Bearer $ENDOR_TOKEN" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` @uuid = `` ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/saved-queries/{{uuid}}/evaluate HTTP/1.1 Authorization: Bearer {{token}} ``` The response returns the resulting data in a nested field under the Query specification. Use the `jq` command to extract the nested data. For the example queries given above, the following command will evaluate the given saved query, and extract the list of Finding objects from the Query response: ```bash theme={null} endorctl api get --resource SavedQuery --uuid \ | jq '.spec.query.spec.query_response.list.objects[]' ``` # Best practices Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/best-practices/index Follow these best practices when using the Endor Labs REST API. ## Using endorctl * Enable [tab-completion](/developers-api/cli/commands/completion). * Use [interactive mode](/developers-api/cli/commands/api#endorctl-api-update-interactive-mode) for creates and updates. ## Optimize queries * Use the [count](/developers-api/rest-api/using-the-rest-api/getting-started#list-parameters) flag if you only need the total number of objects matching the query. * Use [grouping](/developers-api/rest-api/using-the-rest-api/grouping) if you only need the number of objects per unique value of a given field, or a set of fields. * Use [field-masks](/developers-api/rest-api/using-the-rest-api/masks) to return only the fields you need. * [Filter](/developers-api/rest-api/using-the-rest-api/filters) on [common fields](/developers-api/rest-api/using-the-rest-api/data-model/common-fields) such as `uuid` or `meta.name` before resource kind specific fields. # Common fields Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/data-model/common-fields/index Learn about the common fields for all objects in the Endor Labs data model. All objects adhere to the same high-level structure as outlined below. Object specific fields are defined in **Spec**. For more information, see [Resource kinds](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds). ## UUID All objects have a unique **UUID**. You can use UUID to retrieve objects individually through the API. ## Meta All objects include a common nested object called **Meta**. Meta is a mandatory object that contains the common fields for each object, including the following fields. ## TenantMeta Most objects include a common nested object called **TenantMeta**. TenantMeta contains the following field. ### OSS tenant There is a common tenant for all OSS projects called `oss`, to which customers have read access. ## Spec All objects include a common nested object called **Spec**. This mandatory object contains the specification of the object, representing its current state. For more information, see [Resource kinds](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds). ## Context Most objects include a common nested object called **Context**. Contexts keep objects from different scans separated. The context object has the following fields. ### Context types Each context has a type and an id. For example, objects created during a scan of the default branch belong to the **main** context, while objects for non-default branches have the context type **ref**. ## Processing status **Project** and **PackageVersion** objects include a common nested object called **ProcessingStatus**, which contains fields about the processing status of the object (when it was/will be scanned). The processing status object has the following fields: ### Scan state The following scan states are supported. ## Example The following is an example of a **Project** object. ```json expandable theme={null} { "meta": { "create_time": "2023-12-05T00:04:21.853Z", "kind": "Project", "name": "https://github.com/my_organization/my_repository.git", "update_time": "2024-05-01T16:50:03.830911988Z", "version": "v1" }, "processing_status": { "analytic_time": "2024-05-01T16:45:06.483972413Z", "disable_automated_scan": true, "scan_state": "SCAN_STATE_IDLE", "scan_time": "2024-03-18T14:38:31.899249002Z" }, "spec": { "git": { "full_name": "endorlabs/monorepo", "git_clone_url": "git@github.com:my_organization/my_repository.git", "http_clone_url": "https://github.com/my_organization/my_repository.git", "organization": "endorlabs", "path": "monorepo", "web_url": "https://api.github.com/my_organization/my_repository" }, "internal_reference_key": "https://github.com/my_organization/my_repository.git", "platform_source": "PLATFORM_SOURCE_GITHUB" }, "tenant_meta": { "namespace": "my_namespace" }, "uuid": "656e69058032bf0abaaeb681" } ``` # Data model Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/data-model/index Learn about the Endor Labs data model. Objects are persistent entities within the Endor Labs system that represent the results of your scans. Specifically, they can describe: * The projects and package versions that Endor Labs scanned. * The results of the scans, including **ScanResults**, **Findings**, and **Metrics**. * The context used for the scan (for example, main branch vs. pull request). * The policies used for the scans. To create, modify, or delete objects, you need to use the Endor Labs REST API - Either indirectly with the endorctl command-line tool or directly with the REST API. * [Common fields](/developers-api/rest-api/using-the-rest-api/data-model/common-fields): Learn about the common fields for all objects in the Endor Labs data model. * [Resource kinds](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds): Learn about the resource kinds in the Endor Labs data model. # Resource kinds Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds/index Learn about the resource kinds in the Endor Labs data model. Here is an overview diagram of the Endor Labs data model for the most commonly used resource kinds. Lighter shading identifies the objects that are re-computed on every scan. data model This section describes the most commonly used resource kinds. For a complete list of supported resource kinds, see the [Endor Labs OpenAPI documentation](/api-reference/). All objects contain a reference to the project UUID, either as the parent object (`meta.parent_uuid`) or a specific field in the object-specific data if the project is not the direct parent (`spec.project_uuid` if not specified otherwise). Use the following command to get a list of all objects of a given resource kind in your tenant. Here are a few useful options: * `--count` * `--page-size=1` * `--list-all` * `--filter="meta.parent_uuid=="` * `--filter="spec.project_uuid=="` ```bash theme={null} endorctl api list -r ``` ## Project * This is the logical root of all the other information for a given project. * Contains information about the source code location of a project, such as a Git repository, or a package manager package name. * Does not have a parent and is not associated with a context. * The object name is the HTTP clone URL, for example: `"https://github.com/definitelytyped/definitelytyped.git"`. For more information, see the [ProjectService REST API documentation](/api-reference/projectservice/listprojects). ## Repository * Contains information about the source code for a project. * Child of a Project and, just like the Project, does not belong to a context. * There is at most one Repository per Project, but a Project may not have a Repository if there is no source code. * The object name is the same as the Project. For more information, see the [RepositoryService REST API documentation](/api-reference/repositoryservice/listrepositories). ## RepositoryVersion * Contains information about a specific version of a Repository. * Has the Project as the parent. * There are often multiple RepositoryVersions per project. * Each RepositoryVersion is associated with a [Context](/developers-api/rest-api/using-the-rest-api/data-model/common-fields#context). * The object name is the corresponding branch name, tag, or SHA, for example: `"main"`. For more information, see the [RepositoryVersionService REST API documentation](/api-reference/repositoryversionservice/listrepositoryversions). ## PackageVersion * Contains information about a specific version of a package and its dependencies. * Does not have a parent (for historical reasons), but is associated with a [Context](/developers-api/rest-api/using-the-rest-api/data-model/common-fields#context) and connected to the Project through `spec.project_uuid`. * The object name is the corresponding package version name in the format `://@`, for example: `"mvn://org.webjars.npm:types__json-schema@1.2.3"`. For more information, see the [PackageVersionService REST API documentation](/api-reference/packageversionservice/listpackageversions). ### Resolution errors Details about any dependency resolution or call graph generation errors for a package version are stored in `spec.resolution_errors`. There are three categories of resolution errors, each with a separate field that can contain up to one resolution error: 1. **Unresolved** - Details in `spec.resolution_errors.unresolved` if there was an error computing the unresolved dependencies. 2. **Resolved** - Details in `spec.resolution_errors.resolved` if there was an error resolving the dependency versions. 3. **Call graph** - Details in `spec.resolution_errors.call_graph` if there was an error generating the call graph. Each resolution error has a `status_error` field and may also contain details about the `target`, the `operation` that failed, and a `description` of the error. The following status errors are supported: Below is an example resolution error in the **Resolved** category: ```json theme={null} { "spec": { "resolution_errors": { "resolved": { "description": "failed to discover dependency: unable to resolve dependencies for 'requirements': unable to get direct dependencies: unable to install modules to extract dependencies: unable to resolve package version: ResolveModuleVersion: error in pypi json api for: torch, exact version: 1.9.0+cpu, err: package not found in the repository: unable to resolve dependency version: unable to discover dependencies, unable to discover dependencies", "operation": "python:resolvedDependencies:discover", "status_error": "STATUS_ERROR_DEPENDENCY", "target": "pypi://requirements@main" } } } } ``` ## DependencyMetadata * Different from other common resource kinds as it represents the *relationship* between two PackageVersions: The **importer** and the **dependency**. * There is one DependencyMetadata object for every dependency for every PackageVersion. * Has the **importer** PackageVersion as the parent and exists in the same [Namespace](/developers-api/rest-api/using-the-rest-api/data-model/common-fields#tenantmeta) and [Context](/developers-api/rest-api/using-the-rest-api/data-model/common-fields#context) as the parent. * The object name is the same as the **dependency** PackageVersion. * Combine the object name (`meta.name`) and the parent UUID (`meta.parent_uuid`) to get a unique key. * Connected to the Project through `spec.importer_data.project_uuid`. * Details about the relationship are stored in `spec.dependency_data`. For example: * `spec.dependency_data.direct` * `spec.dependency_data.reachable` * `spec.dependency_data.scope` For more information, see the [DependencyMetadataService REST API documentation](/api-reference/dependencymetadataservice/listdependencymetadata). ## LinterResult * Contains the results of scans using third-party programs such as Gitleaks or Semgrep. * Has a RepositoryVersion or PackageVersion as the parent. * Belongs to the same [Context](/developers-api/rest-api/using-the-rest-api/data-model/common-fields#context) as the parent. * Connected to the Project through `spec.project_uuid`. * The object name is the name of the rule that created the result, for example: `"gen-shady-links"`. * The result origin is stored in `spec.origin`, for example: `"LINTER_RESULT_ORIGIN_SECRETS_SCANNER"`. For more information, see the [LinterResultService REST API documentation](/api-reference/linterresultservice/listlinterresults). ## Metric * Contains the output of the analytics processing. * Has a PackageVersion, RepositoryVersion, or Repository as the parent. * Belongs to the same [Context](/developers-api/rest-api/using-the-rest-api/data-model/common-fields#context) as the parent. * Connected to the Project through `spec.project_uuid`. * The object name is the name of the analytic that created the metric, for example: `"package_version_scorecard"`. For more information, see the [MetricService REST API documentation](/api-reference/metricservice/listmetrics). ### Metric types There are many different types of Metrics. The specifics are stored under `spec.metric_values..`, for example: `spec.metric_values.scorefactor.score_factor_list`. Some Metrics have more than one key-value field under `spec.metric_values`. The following table lists all supported Metric types along with the corresponding paths to the Metric specific data under `spec.metric_values`. ## Finding * Contains details of a problem that needs to be fixed. * Has a PackageVersion, RepositoryVersion, or Repository as the parent. * Belongs to the same [Context](/developers-api/rest-api/using-the-rest-api/data-model/common-fields#context) as the parent. * Connected to the Project through `spec.project_uuid`. * There are many different types of Findings and new types can be created by custom [Finding Policies](/platform-administration/policies/finding-policies). * The object name is the Finding type, for example: `"outdated_release"`. For more information, see [Finding names and metadata](#finding-names-and-metadata) below. * The object description contains a more specific description of the Finding, for example: `"Outdated Dependency @babel/plugin-syntax-async-generators@7.8.4"`. * Additional finding type specific data is stored in `spec.finding_metadata`, for example: `spec.finding_metadata.vulnerability`. * PackageVersion Findings often involve both the root PackageVersion and a dependency PackageVersion. The following details about the dependency PackageVersion are available directly in the Finding object: * `spec.target_dependency_name`, for example: `"@babel/plugin-syntax-async-generators"` * `spec.target_dependency_package_name`, for example: `"npm://@babel/plugin-syntax-async-generators@7.8.4"` * `spec.target_dependency_version`, for example: `"7.8.4"` * `spec.finding_metadata.dependency_package_version_metadata` * The UUID of the DependencyMetadata for the dependency is stored in `spec.target_uuid`. * There is one Finding object for every PackageVersion that includes a dependency with a given problem. If 10 PackageVersions include a dependency with a vulnerability then there will be 10 findings for the vulnerability. For more information, see the [FindingService REST API documentation](/api-reference/findingservice/listfindings). ### Finding names and metadata The following table lists all supported values for the Finding `meta.name` field along with an example value for the corresponding `meta.description` and an explanation. ### Finding categories The following finding categories are supported as possible values in the `spec.finding_categories` list. All findings must have at least one category. ### Finding tags The following system defined finding tags are supported as possible values in the `spec.finding_tags` list and referred to as "attributes" in the Endor Labs user interface. These are different from the free-form custom tags that are stored in the [Meta](/developers-api/rest-api/using-the-rest-api/data-model/common-fields#meta) field. ### Exceptions A finding can be exempt from triggering action policies (such as admission and notification policies) if it is matched and marked as dismissed by an exception policy. [Exception policies](/platform-administration/policies/exception-policies) allow you to set any criteria you want to mark findings as dismissed. You can apply an exception policy across all projects, a sub-set of projects, or a specific project, within a tenant. Based on the criteria you set, the exception can persist across multiple package versions. Findings dismissed by one or more exception policies have the `spec.dismiss` field set to `true` and the corresponding policy object UUIDs are listed under the `spec.exceptions.policy_uuids` field. They also carry the `FINDING_TAGS_EXCEPTION` tag. ### Action policies Findings matched by one or more action policies (a.k.a. admission and notification policies) contain the corresponding policy object UUIDs in `spec.actions.policy_uuids`. They also carry a tag corresponding to the specific action, for example, `FINDING_TAGS_CI_WARNING`, `FINDING_TAGS_CI_BLOCKER`, or `FINDING_TAGS_NOTIFICATION`. ## ScanResult * Contains details of a scan such as: * Configuration * Host environment details * Runtime statistics * Findings * Policies triggered * Error logs * [Exit code](/best-practices/troubleshooting/endorctl-exitcodes) * [Scan status](#scan-status) * Has the Project as the parent. * Belongs to the same [Context](/developers-api/rest-api/using-the-rest-api/data-model/common-fields#context) as the scan. For more information, see the [ScanResultService REST API documentation](/api-reference/scanresultservice/listscanresults). ### Scan status The following scan statuses are supported: # Errors Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/errors/index Learn about the Endor Labs REST API error codes and how to handle them Endor Labs uses conventional gRPC and HTTP response codes to indicate the success or failure of an API request. When making API requests, always implement proper error handling to gracefully manage these response codes. ## gRPC status codes Refer to the [gRPC status code documentation](https://grpc.io/docs/guides/status-codes/) for more information. ## HTTP status codes When receiving a 429 status code, implement an exponential backoff strategy to avoid overwhelming the API. # Filters Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/filters/index Learn how to use filters with the Endor Labs REST API. Filters allow you to specify a subset of objects that a request returns, for example: ```bash theme={null} endorctl api list --resource Finding \ --filter "meta.name==dependency_with_critical_vulnerabilities" \ --count ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --data-urlencode "list_parameters.filter=meta.name==dependency_with_critical_vulnerabilities" \ --data-urlencode "list_parameters.count=true" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=meta.name==dependency_with_critical_vulnerabilities&list_parameters.count=true HTTP/1.1 Authorization: Bearer {{token}} ``` ## Keys A filter key specifies the field of the object to match against using a dot-delimited path. For example, given an object: ```json expandable theme={null} { "uuid": "63ef202d090b62ecf3f6655b", "meta": { "name": "Example Object", "tags": ["dev"] }, "spec": { "dependencies": [ { "name": "mvn://org.slf4j:slf4j-api@2.0.0", }, { "name": "mvn://ch.qos.logback:logback-access@1.3.0", } ], "version": { "ref": "v1.6.333", "timestamp": "2024-05-31TT21:04:55.799Z" } } } ``` * `uuid` specifies the root field with the value `"63ef202d090b62ecf3f6655b"` * `meta.name` specifies the nested field with the value `"Example Object"` * `meta.tags` specifies the nested list field containing the values `["dev"]` * `spec.dependencies.name` specifies the nested fields within the list with the values: `"mvn://org.slf4j:slf4j-api@2.0.0"` and `"mvn://ch.qos.logback:logback-access@1.3.0"` * `spec.version.ref` specifies the nested field with the value `"v1.6.333"` For more information, see [Data model](/developers-api/rest-api/using-the-rest-api/data-model). ## Operators The API supports the following filter operators. ### Contains Use `contains` or `not contains` to filter on the content of a list field. The filter treats multiple values as an OR operation, for example: * To get all findings for vulnerabilities that have a fix available OR are in a reachable function use: `spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE, FINDING_TAGS_REACHABLE_FUNCTION]` * To get all findings for vulnerabilities that have a fix available AND are in a reachable function use: `spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE] and spec.finding_tags contains [FINDING_TAGS_REACHABLE_FUNCTION]` * To get all projects that do not have the meta tags "sanity" or "test" use: `meta.tags not contains [sanity, test]` ### In Use `in` or `not in` to filter on the value of a field against one or more given values. The filter treats multiple values as an OR operation, for example: * To get all findings with a "Critical" or "High" severity level use: `spec.finding_level in [FINDING_LEVEL_CRITICAL, FINDING_LEVEL_HIGH]` * To get all findings that are not from the "Maven" or "npm" ecosystems use: `spec.ecosystem not in [ECOSYSTEM_MAVEN, ECOSYSTEM_NPM]` ### Matches Use `matches` to filter on a regex pattern. Due to the nature of regex evaluation, this is much slower than using for example `==` or `!=`. Also due to the nature of regex evaluation, `not matches` is not supported. ### Exists If a field does not exist then it can't be equal to anything, so we use `exists` and `not exists` instead of `!= null` or `== null`. This also covers `{}`, `[]`, etc. ## Values A filter value works with the operator to match against the values at the specified field. Use double quotes to escape string or regex values in a filter, for example: * `uuid in ["64a3b8326dda5fb62bfcceea", "658323c91aa208f231cc7eff", "658323c963ca516ef02d1b02"]` * `meta.name matches "validation bypass"` Filters are case-sensitive by default. To filter with case-insentive values, you can use a regex modifier, for example: * `meta.description matches "(?i)django"` ### Date/Time Values Use `date` to encode date values in a filter, for example: * To filter for objects created after a given date, use a date value with the format `YYYY-MM-DD`: `meta.update_time >= date(2024-05-01)` * To filter for objects created between specific times, use a timestamp values with the [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) format: `meta.create_time >= date(2024-05-01T13:30:00.000Z) and meta.create_time < date(2024-05-01T23:30:00.000Z)` Use `now` to encode relative date values in a filter by a given duration offset, for example: * To filter for objects created in the last 15 minutes, use: `meta.create_time >= now(-12h)` * To filter for objects created in the last 72 hours, use: `meta.create_time >= now(-72h)` ## Combinations Use `and` or `or` to combine multiple filters, for example: * `spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and meta.create_time >= date(2024-05-31)` * `meta.name==archived_source_code_repo or meta.name==outdated_release` ### Nesting filters You can also nest multiple filters together into a single filter with parentheses `()`, for example: * `(spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and spec.level==FINDING_LEVEL_CRITICAL) or (spec.finding_categories contains [FINDING_CATEGORY_SECRETS] and spec.level in [FINDING_LEVEL_CRITICAL, FINDING_LEVEL_HIGH])` # Getting started Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/getting-started/index Learn how to use the Endor Labs REST API. ## Introduction This article describes how to use the Endor Labs REST API. For a quickstart guide, see [Quickstart for Endor Labs REST API](/developers-api/rest-api/quickstart). The Endor Labs command line tool `endorctl` wraps the REST API and lets you interact with Endor Labs without managing REST protocol details. For more information, see [Making a request](#making-a-request) below and the [Endor Labs CLI documentation](/developers-api/cli/commands/api). For a complete list of Endor Labs REST API endpoints, see the [Endor Labs OpenAPI documentation](/api-reference/). ## About requests to the REST API This section describes the elements that make up an API request: * [HTTP method](#http-method) * [Path](#path) * [Headers](#headers) * [Parameters](#parameters) Every request to the REST API includes an HTTP method and a path. Depending on the REST API endpoint, you might also need to specify request headers, authentication information, list parameters, or body parameters. The REST API reference documentation describes the HTTP method, path, and parameters for every endpoint. It also displays example requests and responses for each endpoint. For more information, see the [Endor Labs REST API documentation](/developers-api/rest-api/using-the-rest-api/getting-started/..). ## HTTP method The HTTP method of an endpoint defines the type of action it performs on a given resource. Some common HTTP methods are GET, POST, DELETE, and PATCH. The REST API reference documentation provides the HTTP method for every endpoint. For example, the HTTP method for the [List Findings](/api-reference/findingservice/listfindings) endpoint is GET. Where possible, the Endor Labs REST API strives to use an appropriate HTTP method for each action. ## Path Each endpoint has a path. The [Endor Labs REST API reference documentation](/api-reference/) gives the path for every endpoint. For example, the path for the [List Findings](/api-reference/findingservice/listfindings) endpoint is `https://api.endorlabs.com/v1/namespaces/{tenant_meta.namespace}/findings` and the path for the [Get Finding](/api-reference/findingservice/getfinding) endpoint is `https://api.endorlabs.com/v1/namespaces/{tenant_meta.namespace}/findings/{uuid}`. The curly brackets in a path denote path parameters that you need to specify. Path parameters modify the endpoint path, and your request must include them. For example, the path parameter for the [List Findings](/api-reference/findingservice/listfindings) endpoint is `{tenant_meta.namespace}`. To use this path in your API request, replace `{tenant_meta.namespace}` with the name of the namespace where you want to request a list of findings. To get a specific finding object, add the object UUID to the end of the path. ## Headers Headers provide extra information about the request and the desired response. Following are some examples of headers that you can use in your requests to the Endor Labs REST API. For an example of a request that uses headers, see [Making a request](#making-a-request). ### Authentication All endpoints require authentication. Use the `endorctl init` command to authenticate with Endor Labs. For more information, see [Authentication](/developers-api/rest-api/authentication). For examples, see [Making a request](#making-a-request). ### Accept-Encoding You may optionally use the `Accept-Encoding` header to enable compression of HTTP responses for performance optimization. Endor Labs supports the following encodings: `gzip`, `br` (`Brotli`), and `zstd`. If you specify multiple encodings, gzip takes priority. Ensure that the client can correctly handle the specified encoding. You can provide the `Accept-Encoding` header in the following format: `Accept-Encoding: gzip, br, zstd`. ### Content-Type To improve API performance, set the `Content-Type` header to `application/jsoncompact`. This prevents Endor Labs APIs from returning null or empty values, which is the default behavior. ### Request-timeout Use the `Request-timeout` header to specify the amount of time, in seconds, that you are willing to wait for a server response. For example: `--header "Request-Timeout: 10"`. The corresponding option for `endorctl` requests is `-t/--timeout`, for example: `-t 10s`. ## Parameters Many API methods require or allow you to send additional information in parameters in your request. There are a few different types of parameters: Path parameters, list parameters, and body parameters. ### Path parameters Path parameters modify the endpoint path. These parameters are required in your request. For more information, see [Path](#path). ### List parameters List parameters allow you to control what data is returned for a request. In most cases, these parameters are optional. The documentation for each Endor Labs REST API endpoint describes any list parameters that it supports. For example, all Endor Labs endpoints return one hundred objects by default. You can set `page_size=2` to return two objects instead of 100. You can set `count=true` to just return the number of objects. You can use the `filter` list parameter to only list objects that match a specified list of criteria (see [filters](/developers-api/rest-api/using-the-rest-api/filters)). For examples of requests that use list parameters, see [Making a request](#making-a-request) and [Use cases](/developers-api/rest-api/using-the-rest-api/use-cases). ### Body parameters Body parameters allow you to pass additional data to the API. These parameters can be optional or required, depending on the endpoint. The documentation for each Endor Labs REST API endpoint describes the body parameters that it supports. For more information, see the [Endor Labs OpenAPI documentation](/api-reference/). For example, the [Create Policy](/api-reference/policyservice/createpolicy) endpoint requires that you specify a name, rule, query statement, and resource kinds for the new policy in your request. It also allows you to optionally specify other information, such as a description, actions, or tags to apply to the new policy. For an example of a request that uses body parameters, see [Making a request](#making-a-request). ## Making a request The following example retrieves all findings for reachable functions. For more examples, see [Use cases](/developers-api/rest-api/using-the-rest-api/use-cases). 1. **Setup** Install the Endor Labs CLI on macOS, Windows, or Linux. For more information, see [Install Endor Labs on your local system](/introduction/getting-started#install-endorctl). 2. **Authenticate** Run `endorctl init` and your browser window will open automatically. Select your authentication provider from the available options and complete the authentication process. You can also specify your supported authentication provider manually. `endorctl init --auth-mode google` 3. **Make a request** `endorctl api list --resource Finding --filter "spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION"` Note that you do not have to provide the access token or the namespace when using `endorctl` to access the Endor Labs REST API. 1. **Setup** 2. You must have curl installed on your machine. To check if curl is already installed, run `curl --version`- on the command line. * If the output provides information about the version of curl, that means curl is installed. * If you get a message similar to command not found: curl, that means curl is not installed. Download and install curl. For more information, see the [curl download page](https://curl.se/download.html). 3. Install the Endor Labs CLI on macOS, Windows, or Linux. For more information, see [Install Endor Labs on your local system](/introduction/getting-started#install-endorctl). 4. **Authenticate** 5. Run `endorctl init` and your browser window will open automatically. Select your authentication provider from the available options and complete the authentication process. You can also specify your supported authentication provider manually. `endorctl init --auth-mode google` 6. Store the Endor Labs access token Run the following command from your terminal to get the Endor Labs access token. `endorctl auth --print-access-token` 7. **Choose an endpoint for your request** Choose an endpoint to make a request to. You can explore the Endor Labs REST API documentation to discover endpoints that you can use to interact with Endor Labs. Identify the HTTP method and path of the endpoint. You will send these with your request. For more information, see [HTTP method](#http-method) and [Path](#path). For example, the [List Findings](/api-reference/findingservice/listfindings) endpoint uses the HTTP method POST and the path `/v1/namespaces/{tenant_meta.namespace}/findings`. Identify any required path parameters. Required path parameters appear in curly brackets in the path of the endpoint. Replace each parameter placeholder with the desired value. For more information, see [Path](#path). For example, the [List Findings](/api-reference/findingservice/listfindings) endpoint uses the path `/v1/namespaces/{tenant_meta.namespace}/findings`, and the path parameter is `{tenant_meta.namespace}`. To use this path in your API request, replace `{tenant_meta.namespace}` with the name of the namespace where you want to list the findings. 4. **Choose options for your request** Use the curl command to make your request. For more information, see the [curl documentation](https://curl.se/docs/manpage.html). Specify the following options and values in your request: * `--request` or `-X` followed by the HTTP method as the value. For more information, see [HTTP method](#http-method). > Note: You can also use the shorthand curl options `--get` and `--post` for GET and POST requests respectively. * `--header` or `-H`: * `Authorization`: Pass your authentication token in an Authorization header. You must use `Authorization: Bearer` with the Endor Labs REST API. For more information, see [Authentication](#authentication). * `Accept-Encoding`: Provide the `Accept-Encoding` header in the following format: `Accept-Encoding: gzip` to avoid performance bottlenecks. For more information, see [Accept-Encoding](#accept-encoding). * `Content-Type`: Set the header as `Content-Type: application/jsoncompact` to prevent Endor Labs APIs from returning null or empty value. For more information, see [Content-Type](#content-type). * `Request-timeout`: Specify the amount of time, in seconds, that you are willing to wait for a server response. For more information, see [Request-timeout](#request-timeout). * `--url` followed by the full path as the value. The full path is a URL that includes the base URL for the Endor Labs REST API (`https://api.endorlabs.com`) and the path of the endpoint, like this: `https://api.endorlabs.com/{PATH}`. Replace `{PATH}` with the path of the endpoint. For more information, see [Path](#path). To use list parameters, add a `?` to the end of the path, then append your list parameter name and value in the form `list_parameter.parameter_name=value`. Separate multiple list parameters with `&`. For example, to count the number of "Outdated Release" findings, use `?list_parameters.filter=meta.name==outdated_release&list_parameters.count=true`. For more information, see [List parameters](#list-parameters). > Note: Filters with spaces must be encoded when using curl. Replace spaces with `%20` or use the `--data-urlencode` option for filters containing spaces. * `--data` or `-d` followed by any body parameters within a json object. If you do not need to specify any body parameters in your request, omit this option. For more information, see [Body parameters](#body-parameters). 5. **Make request** 6. Using `--url` ```bash theme={null} curl --request GET \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --header "Content-Type: application/jsoncompact" \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.filter=spec.finding_tags%20contains%20FINDING_TAGS_REACHABLE_FUNCTION" ``` 7. Using `--data-urlencode` ```bash theme={null} curl --request GET \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --header "Content-Type: application/jsoncompact" \ --data-urlencode "spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION" \ "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings" ``` 1. **Setup** Install the Endor Labs CLI on macOS, Windows, or Linux. For more information, see [Install Endor Labs on your local system](/introduction/getting-started#install-endorctl). 2. **Authenticate** 3. Run `endorctl init` and your browser window will open automatically. Select your authentication provider from the available options and complete the authentication process. You can also specify your supported authentication provider manually. `endorctl init --auth-mode google` 4. Store the Endor Labs access token Run the following command from your terminal to get the Endor Labs access token. `endorctl auth --print-access-token` 5. **Choose an endpoint for your request** Choose an endpoint to make a request to. You can explore the Endor Labs REST API documentation to discover endpoints that you can use to interact with Endor Labs. Identify the HTTP method and path of the endpoint. You will send these with your request. For more information, see [HTTP method](#http-method) and [Path](#path). For example, the [List Findings](/api-reference/findingservice/listfindings) endpoint uses the HTTP method POST and the path `/v1/namespaces/{tenant_meta.namespace}/findings`. Identify any required path parameters. Required path parameters appear in curly brackets in the path of the endpoint. Replace each parameter placeholder with the desired value. For more information, see [Path](#path). For example, the [List Findings](/api-reference/findingservice/listfindings) endpoint uses the path `/v1/namespaces/{tenant_meta.namespace}/findings`, and the path parameter is `{tenant_meta.namespace}`. To use this path in your API request, replace `{tenant_meta.namespace}` with the name of the namespace where you want to list the findings. 4. **Make a request** ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION HTTP/1.1 Authorization: Bearer {{token}} ``` # Grouping Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/grouping/index Learn how to group results from the Endor Labs REST API. There are many scenarios where it is useful to group the objects returned by the Endor Labs REST API in different ways. Like [filter keys](/developers-api/rest-api/using-the-rest-api/filters#keys), a group-aggregation-paths key specifies the field, or fields, by which to group the objects, using a dot-delimited path. For example, the following request returns the count of findings for each severity level: ```bash theme={null} endorctl api list --resource Finding \ --filter "spec.finding_categories contains FINDING_CATEGORY_VULNERABILITY" \ --group-aggregation-paths "spec.level" \ --timeout 60s ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --header "Request-Timeout: 60" \ --data-urlencode "list_parameters.filter=spec.finding_categories contains FINDING_CATEGORY_VULNERABILITY" \ --data-urlencode "list_parameters.group.aggregation_paths=spec.level" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings \ | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.finding_categories contains FINDING_CATEGORY_VULNERABILITY&list_parameters.group.aggregation_paths=spec.level HTTP/1.1 Content-type: application/json Authorization: Bearer {{token}} Request-Timeout: 60 ``` ```bash expandable theme={null} { "group_response": { "groups": { "[{\"key\":\"spec.level\",\"value\":\"FINDING_LEVEL_CRITICAL\"}]": { "aggregation_count": { "count": 49 } }, "[{\"key\":\"spec.level\",\"value\":\"FINDING_LEVEL_HIGH\"}]": { "aggregation_count": { "count": 166 } }, "[{\"key\":\"spec.level\",\"value\":\"FINDING_LEVEL_LOW\"}]": { "aggregation_count": { "count": 31 } }, "[{\"key\":\"spec.level\",\"value\":\"FINDING_LEVEL_MEDIUM\"}]": { "aggregation_count": { "count": 202 } } } } } ``` ## Group by path The following options are available to group objects based on the value of a field in a given path. For the complete list of all `endorctl api list` options, see [flags and variables](/developers-api/cli/commands/api#endorctl-api-list-flags-and-variables). For the complete list of all HTTP list parameters, see [list parameters](/developers-api/rest-api/using-the-rest-api/getting-started#list-parameters). ### Group by path example The following example uses all options to group package versions by call graph [resolution error](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#resolution-errors). For each group, it lists the UUIDs, counts the ecosystems, and shows the unique ecosystems: ```bash theme={null} endorctl api list --resource PackageVersion \ --filter "spec.resolution_errors.call_graph exists" \ --group-aggregation-paths "spec.resolution_errors.call_graph.status_error" \ --group-show-aggregation-uuids \ --group-unique-count-paths "spec.ecosystem" \ --group-unique-value-paths "spec.ecosystem" \ --timeout 60s ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --header "Request-Timeout: 60" \ --data-urlencode "list_parameters.filter=spec.resolution_errors.call_graph exists" \ --data-urlencode "list_parameters.group.aggregation_paths=spec.resolution_errors.call_graph.status_error" \ --data-urlencode "list_parameters.group.show_aggregation_uuids=true" \ --data-urlencode "list_parameters.group.unique_value_paths=spec.ecosystem" \ --data-urlencode "list_parameters.group.unique_count_paths=spec.ecosystem" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/package-versions \ | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/package-versions?list_parameters.filter=spec.resolution_errors.call_graph exists&list_parameters.group.aggregation_paths=spec.resolution_errors.call_graph.status_error&list_parameters.group.show_aggregation_uuids=true&list_parameters.group.unique_value_paths=spec.ecosystem&list_parameters.group.unique_count_paths=spec.ecosystem HTTP/1.1 Content-type: application/json Authorization: Bearer {{token}} Request-Timeout: 60 ``` ```bash expandable theme={null} { "group_response": { "groups": { "[{\"key\":\"spec.resolution_errors.call_graph.status_error\",\"value\":\"STATUS_ERROR_CALL_GRAPH\"}]": { "aggregation_count": { "count": 10 }, "aggregation_uuids": [ "6494c13cdcb266d2af02804f", "64ace2dd05228d0041488208", "64ace2dc05228d00414881eb", "64af3a042efc155e48304bf2", "65b86b4a0f460309eac456b5", "64ace2dc832ee78dd03d85b0", "64c190aa17e6bfc2548f7a48", "64af39d2bebf530905411327", "64c190a817e6bfc2548f7a19", "64cc2b68727cd13ec36860c8" ], "unique_counts": { "spec.ecosystem": { "count": 2 } }, "unique_values": { "spec.ecosystem": [ "ECOSYSTEM_MAVEN", "ECOSYSTEM_PYPI" ] } }, "[{\"key\":\"spec.resolution_errors.call_graph.status_error\",\"value\":\"STATUS_ERROR_INTERNAL\"}]": { "aggregation_count": { "count": 2 }, "aggregation_uuids": [ "6632e2d6b7765d736fac1865", "664ba7986fafc782b3cda1f6" ], "unique_counts": { "spec.ecosystem": { "count": 1 } }, "unique_values": { "spec.ecosystem": [ "ECOSYSTEM_NPM" ] } }, "[{\"key\":\"spec.resolution_errors.call_graph.status_error\",\"value\":\"STATUS_ERROR_MISSING_ARTIFACT\"}]": { "aggregation_count": { "count": 23 }, "aggregation_uuids": [ "65c3e90ae2dd352a18b6f852", "64b99a3b3d5f8dc732555200", "64c190a921d68642091aa015", "650a2457204ab859367160a2", "650a245780113616f95f770e", "65d6840edb5cf8c9839c3d47", "65e8c21647aae08e2a4e5f5c", "64c190a921d68642091aa027", "64c190a958d2eff448df09e1", "650a2457204ab859367160a6", "64c190aa58d2eff448df09f0", "64af0879c41c606cbcef6288", "64c190ab17e6bfc2548f7a4d", "64c190aa17e6bfc2548f7a41", "64c190a958d2eff448df09ec", "64c190ab21d68642091aa033", "64c190ab58d2eff448df09f3", "64b99a3b6883c0ec1c456c3a", "64c190aa21d68642091aa02f", "64b99a3ce3b06b2f8a465bdc", "64c190a917e6bfc2548f7a35", "64b99a3b6883c0ec1c456c39", "650a24573e183ec1be29adc6" ], "unique_counts": { "spec.ecosystem": { "count": 1 } }, "unique_values": { "spec.ecosystem": [ "ECOSYSTEM_MAVEN" ] } }, "[{\"key\":\"spec.resolution_errors.call_graph.status_error\",\"value\":\"STATUS_ERROR_VENV\"}]": { "aggregation_count": { "count": 10 }, "aggregation_uuids": [ "64c41863da2fbc7700d12a0e", "64c845aca83e181b82ef9041", "64dd4f61177264d779e203f3", "64c418647146e5738bf0af2d", "64c845ac41f581de1a6592d1", "64c845ac41f581de1a6592d0", "664be4bc6fafc782b363d8e3", "652e0bcb1d4d2ceedc87a376", "66311e48bf25e232ab24b68c", "64d6ce776e5804222a2726de" ], "unique_counts": { "spec.ecosystem": { "count": 1 } }, "unique_values": { "spec.ecosystem": [ "ECOSYSTEM_PYPI" ] } } } } } ``` ## Group by time The Endor Labs REST API also provides options to group objects by a given time interval. Common time fields include `meta.create_time` and `meta.update_time`, but you can sort objects based on any time field. For example, to group objects based on create time in 2 week intervals, set the aggregation path to `meta.create_time`, the time interval to `GROUP_BY_TIME_INTERVAL_WEEK` and the group size to `2`. The following options are available to group objects based on the value of a time field in a given path. For the complete list of all HTTP list parameters, see [list parameters](/developers-api/rest-api/using-the-rest-api/getting-started#list-parameters). ### Time intervals The following time intervals are supported. ### Group by time example The following example requests the UUIDs of all critical findings, grouped by create time in two-week intervals: ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --header "Request-Timeout: 60" \ --data-urlencode "list_parameters.filter=spec.level==FINDING_LEVEL_CRITICAL" \ --data-urlencode "list_parameters.group_by_time.aggregation_paths=meta.create_time" \ --data-urlencode "list_parameters.group_by_time.interval=GROUP_BY_TIME_INTERVAL_WEEK" \ --data-urlencode "list_parameters.group_by_time.group_size=2" \ --data-urlencode "list_parameters.group_by_time.show_aggregation_uuids=true" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings \ | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.level==FINDING_LEVEL_CRITICAL&list_parameters.group_by_time.aggregation_paths=meta.create_time&list_parameters.group_by_time.interval=GROUP_BY_TIME_INTERVAL_WEEK&list_parameters.group_by_time.group_size=2&list_parameters.group_by_time.show_aggregation_uuids=true HTTP/1.1 Content-type: application/json Authorization: Bearer {{token}} Request-Timeout: 60 ``` ```bash expandable theme={null} { "group_response": { "groups": { "\"2024-01-28T00:00:00Z\"": { "aggregation_count": { "count": 7 }, "aggregation_uuids": [ "65c02da021a5d767fc147ec0", "65c02da021a5d767fc147ec3", "65c02da0aa4b66fa5009eaec", "65c02da0056f94b6129aa209", "65c02da021a5d767fc147eca", "65c02da1aa4b66fa5009eaf9", "65c02daa056f94b6129aa46f" ], "unique_counts": {}, "unique_values": {} }, "\"2024-03-10T00:00:00Z\"": { "aggregation_count": { "count": 2 }, "aggregation_uuids": [ "65faf8ec357952c8eda2d36b", "65fcdcedd40334d9e0065748" ], "unique_counts": {}, "unique_values": {} }, "\"2024-03-24T00:00:00Z\"": { "aggregation_count": { "count": 2 }, "aggregation_uuids": [ "660728d190fdb066027d07bb", "660728d8bddd7358d570ce9c" ], "unique_counts": {}, "unique_values": {} }, "\"2024-04-07T00:00:00Z\"": { "aggregation_count": { "count": 15 }, "aggregation_uuids": [ "6615c531bb58b077e43cbb16", "6615c531e2a0c32733a7d50b", "6615c531e2a0c32733a7d514", "66216bb723ebef7ca3f4571a", "66216bb7c28c6f37b51cd0e8", "66216bb723ebef7ca3f4571d", "66216bc62c21fa9407eda175", "66216bc6c28c6f37b51cd2d4", "66216bc62c21fa9407eda17b", "66216bd72c21fa9407eda210", "66216bd823ebef7ca3f459a8", "66216bd823ebef7ca3f459ab", "66216bd8c28c6f37b51cd381", "66216be623ebef7ca3f45a8a", "66216be6c28c6f37b51cd465" ], "unique_counts": {}, "unique_values": {} }, "\"2024-04-21T00:00:00Z\"": { "aggregation_count": { "count": 1 }, "aggregation_uuids": [ "66341d55f9aa19f4b730a74c" ], "unique_counts": {}, "unique_values": {} }, "\"2024-05-19T00:00:00Z\"": { "aggregation_count": { "count": 19 }, "aggregation_uuids": [ "664be2cc6fafc782b35fdc89", "664be2cc6fafc782b35fdceb", "664be2d56fafc782b35ff0d8", "664be2d56fafc782b35ff0e0", "664be2d5f420988edd47792d", "664be2dd67636bf844aedcae", "664be2dd6fafc782b36000a8", "664be2dd6fafc782b36000aa", "664be2ddf420988edd4788eb", "664be2e867636bf844aef4e9", "664be2e8f420988edd47a140", "664be2e8f420988edd47a148", "6656ababd2d288f1981ea2ba", "6656ababce82b72012f10bbc", "6656ababce82b72012f10bbd", "6656abab252554c986334a6b", "6656ababd2d288f1981ea2bd", "6656abab252554c986334a6d", "6656abacce82b72012f10bbf" ], "unique_counts": {}, "unique_values": {} }, "\"2024-06-02T00:00:00Z\"": { "aggregation_count": { "count": 5 }, "aggregation_uuids": [ "665fa482c980f9f8157e08c3", "6660a9f0e238ad93ad92089e", "6660a9f05728ef99cf0c8535", "6660a9f0b70974e544ccd05a", "6660a9f05728ef99cf0c853f" ], "unique_counts": {}, "unique_values": {} } } } } ``` # Using the REST API Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/index Learn how to use the Endor Labs REST API to create integrations, retrieve data, troubleshoot problems, and automate your workflows. The following sections provide information on using the Endor Labs REST API. Learn how to use the Endor Labs REST API. Learn about the Endor Labs data model. Learn how to use filters with the Endor Labs REST API. Learn how to use field masks with the Endor Labs REST API. Learn how to navigate through paginated responses from the Endor Labs REST API. Learn how to sort results from the Endor Labs REST API. Learn how to group results from the Endor Labs REST API. Examples of common use cases for interacting with the Endor Labs REST API. Examples of advanced use cases when interacting with the Endor Labs REST API. Follow these best practices when using the Endor Labs REST API. Learn how to use Endor Labs REST API with Postman. Learn how to diagnose and resolve common problems for the Endor Labs REST API. Learn about the Endor Labs REST API error codes and how to handle them. # Masks Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/masks/index Learn how to use field masks with the Endor Labs REST API. Field masks allow you to specify a subset of fields that each returned object includes. Similar to [filter keys](/developers-api/rest-api/using-the-rest-api/filters#keys), a field-mask key specifies the field to return, using a dot-delimited path. The following example shows how to get just the description and severity for all findings: ```bash theme={null} endorctl api list --resource Finding \ --field-mask "meta.description,spec.level" ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.mask=meta.description,spec.level" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.mask=meta.description,spec.level HTTP/1.1 Authorization: Bearer {{token}} ``` ## jq The Endor Labs REST API returns results in json format so it is often convenient to use the `jq` command-line json processor to parse or format the results. The following example shows how to use `jq` to extract just the description value from the above request: ```bash theme={null} endorctl api list --resource Finding \ --field-mask "meta.description,spec.level" \ | jq '.list.objects[].meta.description' ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.mask=meta.description,spec.level" \ | jq '.list.objects[].meta.description' ``` Lists of objects are always nested under `.list.objects[]`, but `endorctl api get` returns a single object directly. To extract the object UUID from an object returned by an `endorctl api get` command, the `jq` command is `jq '.uuid'`, as opposed to `jq '.list.objects[].uuid'`. For more information, see the [jq documentation](https://jqlang.github.io/jq/tutorial/). # Pagination Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/pagination/index Learn how to navigate through paginated responses from the Endor Labs REST API. ## About Pagination When a response from the REST API includes many results, Endor Labs paginates the results and returns a subset of the results. For example, GET `/v1/namespaces/{tenant_meta.namespace}/findings` only returns 100 findings from the given namespace even if the namespace has more than 100 findings. This makes the response easier to handle for servers and for people. You can use the additional data from the list response to request additional pages of data. This article explains how to request additional pages of results for paginated responses and how to change the number of results returned on each page. ## Fetch all resources with `--list-all` The `endorctl` CLI provides the `--list-all` flag that allows you to fetch all results. Internally, `endorctl` handles the pagination through multiple requests. ```bash theme={null} endorctl api list --resource Finding --list-all ``` ## Using `page_size` The `page_size` field allows you to control the number of elements returned. By default, this value is 100, with a maximum of 500. The higher this value is, the longer it may take to get a result. ```bash theme={null} endorctl api list --resource Finding \ --page-size=50 ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.page_size=50" ``` ## Iterating through results You can iterate through results using the `page_id` or `page_token` fields. ### Using `page_id` When a response spans multiple pages, it includes a `next_page_id` value. Use this value to fetch additional pages of results. For example, the response to the above request contains the first 50 elements in the `objects` field along with the following values in the `response` field: ```json theme={null} { "list": { "objects": [ ... ], "response": { "next_page_id": "633dd86976186a89d64628c1", "next_page_token": 50 } } } ``` To access the next page of results, you can use the `next_page_id` value as the value of `page_id` in the next request. For example: ```bash theme={null} endorctl api list --resource Finding \ --page-size=50 \ --page-id=633dd86976186a89d64628c1 ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.page_size=50&list_parameters.page_id=633dd86976186a89d64628c1" ``` This returns the next 50 elements, starting after the last element of the previous page. ### Using `page_token` `page_token` and `next_page_token` provide the same pagination capability as `page_id` and `next_page_id`, using a numeric offset instead of a cursor. However, we recommend using `page_id` and `next_page_id` as they offer better performance for the request. # Postman Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/postman/index Learn how to use Endor Labs REST API with Postman ## Download Postman Download Postman from [here](https://www.postman.com/downloads/). You can also use [Postman on the web](https://go.postman.co/home). ## Download the Endor Labs OpenAPI json You can download the Endor Labs REST API specifications directly from the docs site. Each file is served as a static asset. * [openapi.v3.json](https://docs.endorlabs.com/api-reference/openapi.v3.json): Compact OpenAPI 3.x specification that is suitable for most use cases. * [openapi.full.v3.json](https://docs.endorlabs.com/api-reference/openapi.full.v3.json): Full OpenAPI 3.x specification that includes all schemas and operations. * [openapiv2.swagger.json](https://docs.endorlabs.com/api-reference/openapiv2.swagger.json): Full Swagger 2.0 specification for tools that do not yet support OpenAPI 3.x. ## Import Endor Labs API json file in Postman 1. Open the Postman application. 2. Click **Import** and select the downloaded API specification file. 3. Select **OpenAPI 3.0 with Postman Collection** and click **Import**. Postman adds the Endor REST API collection to your workspace. It may take a couple of minutes to load the entire collection because of the size. ## Configure Endor REST API collection To use the Endor Labs APIs effectively with Postman you need to set the appropriate variables and configure authentication. Before you proceed further, get your API Key and API Secret from the Endor Labs user interface or endorctl. See [REST API authentication](/developers-api/rest-api/authentication#api-key-and-secret) for more information. Endor Labs APIs require a bearer token from the `CreateAPIReq` endpoint. You need to add a pre-request script to obtain this token in the collection. The pre-request script runs when you initiate an API request and fetches the bearer token for your API request. The pre-request script also adds the following headers to the request: * `'Content-Type': 'application/jsoncompact'` * `'Accept-Encoding': 'gzip, deflate, br, zstd'` We recommend that you create a new environment in Postman to run the APIs. You can save your variables in the environment and not the collection so that secrets are not exposed if you want to export and share the collection. You can also save the variables in the collection and modify the pre-request script to run the APIs without creating an environment. ### Create an environment in Postman 1. Click **Environments** in the left sidebar. 2. Click **Create New Environment**. 3. Enter a name for your environment. ### Configure variables in the environment 1. Click **Environments** in the left sidebar. 2. Select your Endor Labs API environment. 3. Create a variable with the name, `baseUrl` and enter `https://api.endorlabs.com` as the value. 4. Create the following variables with information that your API Key and API Secret. * `apiKey` : Your API key * `apiSecret` : Your API secret 5. Create a variable with the name, `bearerToken` and leave it as empty. Postman Variables 6. Save the changes. ### Configure authentication in the Endor REST API collection 1. Select Endor REST API collection and select the **Authorization** tab. 2. Select Bearer Token as the **Auth Type**. 3. Enter `{{bearerToken}}` in the **Bearer Token** field. Postman Authentication 4. Save the changes. ## Add the pre-request script to the Endor REST API collection 1. Select Endor REST API collection and select the **Scripts** tab. 2. Select **Pre-request**. 3. Enter the following JavaScript code as the pre-request script. ```javascript theme={null} const getTokenEndpoint = pm.environment.get("baseUrl") + '/v1/auth/api-key'; const apiKey = pm.environment.get("apiKey"); const apiSecret = pm.environment.get("apiSecret"); const requestOptions = { method: 'POST', url: getTokenEndpoint, header: { 'Content-Type': 'application/jsoncompact', 'Accept-Encoding': 'gzip, deflate, br, zstd' }, body: { mode: 'raw', raw: JSON.stringify({ "key": apiKey, "secret": apiSecret }) } }; pm.sendRequest(requestOptions, function(err, response) { if (err) { console.log(err); } else { const jsonResponse = response.json(); pm.environment.set("bearerToken", jsonResponse.token); // Set headers for the main request pm.request.headers.add({ key: 'Content-Type', value: 'application/jsoncompact' }); pm.request.headers.add({ key: 'Accept-Encoding', value: 'gzip, deflate, br, zstd' }); } }); ``` Postman Pre-request Script 4. Save the changes. ## Run Endor Labs API from Postman 1. Click **Collections** in the left sidebar. 2. Expand Endor REST API collection and select the API that you want to run. 3. Configure the parameters in the **Params** tab. 4. Select the Endor Labs API environment from the Environments drop-down list. 5. Enter the name of your namespace in the `:tenant_meta.namespace` or `:target_namespace` if your API request applies to a namespace. 6. Click **Send** to send the API request. ## Customize and share Postman collection You can configure parameters for multiple APIs according to your requirements, save the collection, and share the collection to quickly distribute API requests tailored for your organization. For example, you might want to create multiple collections that apply to different namespaces and use different parameters for the namespaces. You can customize the parameters for each use case and export the collection for distribution in your development team. ## Endor Labs API with Postman: An Example Consider a scenario where you need to fetch findings that have a CVSS score of more than 9.7. You need to run the `ListFindings` API, which is available under `Endor REST API > V1 > Namespaces > {tenant_meta.namespace} > findings` in the collection. In the **Params** tab, select only `list_parameters.filter` as the key and enter `spec.finding_metadata.vulnerability.spec.cvss_v3_severity.score > 9.7` as the value. Replace `:tenant_meta.namespace` with the name of your namespace and click Send. Postman Example Request The response contains the list of findings that are vulnerabilities with CVSS score greater than 9.7. Postman Example Response # Sorting Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/sorting/index Learn how to sort results from the Endor Labs REST API. Sort allows you to sort objects in ascending (default) or descending order. Similar to [filter keys](/developers-api/rest-api/using-the-rest-api/filters#keys), a sort-path key specifies the field to sort the objects by, using a dot-delimited path. The following example shows how to sort findings based on create time, in descending order: ```bash theme={null} endorctl api list --resource Finding \ --sort-path "meta.create_time" \ --sort-order descending ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.sort.path=meta.create_time&list_parameters.sort.order=SORT_ENTRY_ORDER_DESC" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = `` @namespace = `` ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.sort.path=meta.create_time&list_parameters.sort.order=SORT_ENTRY_ORDER_DESC HTTP/1.1 Authorization: Bearer {{token}} ``` ### Sort order The following sort orders are supported: # Troubleshooting Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/troubleshooting/index Learn how to diagnose and resolve common problems for the Endor Labs REST API. For a full list of error code descriptions, see [Errors](/developers-api/rest-api/using-the-rest-api/errors). ## Invalid authorization If Endor Labs can't verify your access token (for example, it's empty or expired), Endor Labs terminates the request and returns an invalid authorization response. ```json theme={null} { "code": 16, "message": "Invalid authorization header: Bearer", "details": [ { "@type": "type.googleapis.com/internal.endor.ai.rpc.v1.HTTPErrorInfo", "status_code": 401 } ] } ``` ### Remediation Try creating a new token or, if you have a valid API key and secret in your `~/.endorctl/config.yaml` file, unsetting the environment variable (`unset ENDOR_TOKEN`). For more information, see [Authentication](/developers-api/rest-api/authentication). ## Permission Denied If your access token lacks the required permissions for a namespace or operation, Endor Labs terminates the request and returns an unauthorized response. ```json theme={null} { "code": 7, "message": "Unauthorized request for given endpoint", "details": [ { "@type": "type.googleapis.com/internal.endor.ai.rpc.v1.HTTPErrorInfo", "status_code": 403 } ] } ``` ### Remediation Check the value of the `ENDOR_NAMESPACE` environment variable, the variable with the same name in the `~/.endorctl/config.yaml file`, or the API endpoint URL. For more information, see [Authentication](/developers-api/rest-api/authentication). ## Context deadline exceeded If it takes too long to process an API request, Endor Labs will terminate the request and you will receive a timeout response and a "context deadline exceeded" message. ```json theme={null} { "code": 4, "message": "context deadline exceeded", "details": [] } ``` Endor Labs reserves the right to change the timeout window to protect the speed and reliability of the API. ### Remediation You can [increase the request timeout limit](/developers-api/rest-api/using-the-rest-api/getting-started#request-timeout) or you can try to [simplify your request](/developers-api/rest-api/using-the-rest-api/getting-started#list-parameters). For instance, if you are requesting 100 items per page, try requesting fewer items. For more information, see [Best practices](/developers-api/rest-api/using-the-rest-api/best-practices). ## Invalid argument If a request is missing a required field, or includes a non-existent field, Endor Labs will return an "invalid argument" response. The response `message` field contains details about the error, such as the field name and the specific problem with it. For example, Endor Labs returns the following response if you request findings with the field mask `uui` instead of `uuid`: ```json theme={null} { "code": 3, "message": "mask: proto: invalid path "uui" for message "internal.endor.ai.endor.v1.Finding"", "details": [ { "@type": "type.googleapis.com/internal.endor.ai.rpc.v1.HTTPErrorInfo", "status_code": 400 } ] } ``` ### PATCH requests Here is an example response to an PATCH (update) request that sent a Finding as the payload instead of an [UpdateFinding](/api-reference/findingservice/updatefinding): ```json theme={null} { "code": 3, "message": "invalid Finding.Meta: value is required; invalid Finding.Spec: value is required", "details": [ { "@type": "type.googleapis.com/internal.endor.ai.rpc.v1.HTTPErrorInfo", "status_code": 400 } ] } ``` #### Remediation Make sure to use the right data structure as the payload for your PATCH requests. For example: ```json theme={null} { "request" : { "update_mask": "meta.tags" }, "object" : { "uuid" : "", "meta" : { "tags": [ "" ] } } } ``` # Use cases Source: https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/use-cases/index Examples of common use cases for interacting with the Endor Labs REST API. See also [Best practices](/developers-api/rest-api/using-the-rest-api/best-practices) for tips on how to optimize queries. ## Get list of projects ```bash theme={null} endorctl api list --resource Project ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/projects HTTP/1.1 Authorization: Bearer {{token}} ``` Add one or more [field-masks](/developers-api/rest-api/using-the-rest-api/masks) to limit the fields returned for each object. For example, set the field-mask to `meta.name` to only get the name and UUID of all projects. The UUID is always returned. ```bash theme={null} endorctl api list --resource Project --field-mask meta.name ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects?list_parameters.mask=meta.name" \ | jq '.list.objects[].uuid' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/projects?list_parameters.mask=meta.name HTTP/1.1 Authorization: Bearer {{token}} ``` ## Get project UUID The project UUID connects all the objects for a given project. One way to get the project UUID is to extract it from the `uuid` field in the Project object. For more information, see [Resource kinds](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds). ```bash theme={null} endorctl api get --resource Project --name | jq '.uuid' ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects?list_parameters.filter=meta.name==" \ | jq '.list.objects[].uuid' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/projects?list_parameters.filter=meta.name== HTTP/1.1 Authorization: Bearer {{token}} ``` ## Get list of findings for a project Use the following [filter](/developers-api/rest-api/using-the-rest-api/filters) to get a list of findings for a given project: `spec.project_uuid==` ```bash theme={null} endorctl api list --resource Finding --filter "spec.project_uuid==" ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=spec.project_uuid==" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.project_uuid== HTTP/1.1 Authorization: Bearer {{token}} ``` ## Get number of findings for a project Add the `--count` flag to just get the number of findings. This is much faster than retrieving the objects. ```bash theme={null} endorctl api list --resource Finding --filter "spec.project_uuid==" --count ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=spec.project_uuid==" \ --data-urlencode "list_parameters.count=true" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.project_uuid==&list_parameters.count=true HTTP/1.1 Authorization: Bearer {{token}} ``` ## Get number of findings for a project by severity Use [grouping](/developers-api/rest-api/using-the-rest-api/grouping) to get the number of findings by severity. ```bash theme={null} endorctl api list --resource Finding \ --filter "spec.project_uuid==" \ --group-aggregation-paths "spec.level" ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --data-urlencode "list_parameters.filter=spec.project_uuid==" \ --data-urlencode "list_parameters.group.aggregation_paths=spec.level" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings \ | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.project_uuid==&list_parameters.group.aggregation_paths=spec.level HTTP/1.1 Content-type: application/json Authorization: Bearer {{token}} ``` ## Get list of findings for reachable functions Use the following filter to get a list of findings for reachable functions: `spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION` For a list of all finding attributes, see [Finding tags](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#finding-tags). ```bash theme={null} endorctl api list --resource Finding \ --filter "spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION" ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION HTTP/1.1 Authorization: Bearer {{token}} ``` ## Get list of findings for reachable functions for a project Combine the previous filters to get a list of findings for reachable functions for a given project: `spec.project_uuid== and spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION` ```bash theme={null} endorctl api list --resource Finding \ --filter "spec.project_uuid== and spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION" ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=spec.project_uuid== and spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.project_uuid== and spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION HTTP/1.1 Authorization: Bearer {{token}} ``` ## Get list of findings in a category Use the following filter to get a list of findings in the RSPM category: `spec.finding_categories contains FINDING_CATEGORY_SCPM` For a list of all finding categories, see [Finding categories](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#finding-categories). ```bash theme={null} endorctl api list --resource Finding \ --filter "spec.finding_categories contains FINDING_CATEGORY_SCPM" ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=spec.finding_categories contains FINDING_CATEGORY_SCPM" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.finding_categories contains FINDING_CATEGORY_SCPM HTTP/1.1 Authorization: Bearer {{token}} ``` ## Get list of findings for a vulnerability Use the following filter to get a list of findings for a given vulnerability, for example `"CVE-2024-53677"` or `"GHSA-43mq-6xmg-29vm"`: `spec.finding_metadata.vulnerability.spec.aliases contains CVE-2024-53677` > Note: You can replace the CVE ID in the example with any other vulnerability ID type, such as GHSA, BIT, GO, PYSEC, or OVAL. ```bash theme={null} endorctl api list --resource Finding \ --filter "spec.finding_metadata.vulnerability.spec.aliases contains CVE-2024-53677" ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=spec.finding_metadata.vulnerability.spec.aliases contains CVE-2024-53677" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.finding_metadata.vulnerability.spec.aliases contains CVE-2024-53677 HTTP/1.1 Authorization: Bearer {{token}} ``` ## Get list of findings for a code owner Use the `spec.code_owners.owners` field to filter findings based on code owner. > Note: Code owners are automatically assigned based on the [**CodeOwners**](/api-reference/codeownersservice/listcodeowners) object for the project, which Endor Labs generates from the CODEOWNERS file in the default branch. For projects without a CODEOWNERS file, manage the CodeOwners object through the API. ```bash theme={null} endorctl api list --resource Finding \ --filter "spec.code_owners.owners contains " \ --timeout 100s ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --header "Request-Timeout: 100" \ --data-urlencode "list_parameters.filter=spec.code_owners.owners contains " \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.code_owners.owners contains HTTP/1.1 Authorization: Bearer {{token}} ``` ## Group findings by code owner Use the `spec.code_owners.owners` field to group findings based on code owner. > Note: Code owners are automatically assigned based on the [**CodeOwners**](/api-reference/codeownersservice/listcodeowners) object for the project, which Endor Labs generates from the CODEOWNERS file in the default branch. For projects without a CODEOWNERS file, manage the CodeOwners object through the API. ```bash theme={null} endorctl api list --resource Finding \ --group-aggregation-paths "spec.code_owners.owners" \ --timeout 100s ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --header "Request-Timeout: 100" \ --data-urlencode "list_parameters.group.aggregation_paths=spec.code_owners.owners" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings \ | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.group.aggregation_paths=spec.code_owners.owners HTTP/1.1 Content-type: application/json Authorization: Bearer {{token}} ``` ## Get finding snooze history Endor Labs captures snooze updates as **FindingLog** objects. ```bash theme={null} endorctl api list --resource FindingLog \ --filter "spec.finding_uuid== and spec.operation==OPERATION_UPDATE" \ --field-mask "meta.create_time,meta.created_by,spec.snooze" ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=spec.finding_uuid== and spec.operation==OPERATION_UPDATE" \ --data-urlencode "list_parameters.mask=meta.create_time,meta.created_by,spec.snooze" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/finding-logs ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/finding-logs?list_parameters.filter=spec.finding_uuid== and spec.operation==OPERATION_UPDATE&list_parameters.mask=meta.create_time,meta.created_by,spec.snooze HTTP/1.1 Authorization: Bearer {{token}} ``` ## Get Endor Labs scores for an OSS package 1. Set the namespace to `"oss"` because the OSS tenant stores data for OSS packages. 2. Endor Labs stores package version scores in the `"package_version_scorecard"` **Metric** object, in the `spec.metric_values.scorecard.score_card.category_scores` field, so you need to get this Metric object for the given OSS package. For more information, see the [Metric resource kind documentation](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#metric). 3. To get Metric objects belonging to a given package version, get the UUID of the corresponding **PackageVersion** object. The PackageVersion object name must be in the format `://@`, for example: `"mvn://ch.qos.logback:logback-core@1.3.3"`. For more information, see the [PackageVersion resource kind documentation](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#packageversion). Once you have the PackageVersion object, use the following `jq` command to extract the UUID: `jq '.list.object[].uuid'` 4. Get the Metric object corresponding to the PackageVersion UUID using the following two filters: 1. `meta.name==package_version_scorecard` 2. `meta.parent_uuid==` 5. Use the following `jq` command to extract just the Endor Labs scores from the Metric object: `jq '.list.objects[].spec.metric_values.scorecard.score_card.category_scores'` ```bash theme={null} # Get the PackageVersion and extract the uuid UUID=$(endorctl api list \ --namespace oss \ --resource PackageVersion \ --filter "meta.name==mvn://ch.qos.logback:logback-core@1.3.3" \ | jq '.list.objects[].uuid') # Get the Metric and extract the Endor Labs scores endorctl api list \ --namespace oss \ --resource Metric \ --filter "meta.name==package_version_scorecard and meta.parent_uuid==$UUID" \ | jq '.list.objects[].spec.metric_values.scorecard.score_card.category_scores' ``` ```bash theme={null} # Get the PackageVersion and extract the uuid UUID=$(curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=meta.name==mvn://ch.qos.logback:logback-core@1.3.3" \ https://api.endorlabs.com/v1/namespaces/oss/package-versions \ | jq '.list.objects[].uuid') # Get the Metric and extract the Endor Labs scores curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=meta.name==package_version_scorecard and meta.parent_uuid==$UUID" \ https://api.endorlabs.com/v1/namespaces/oss/metrics \ | jq '.list.objects[].spec.metric_values.scorecard.score_card.category_scores' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = ### GET {{baseUrl}}/v1/namespaces/oss/package-versions?list_parameters.filter=meta.name==mvn://ch.qos.logback:logback-core@1.3.3 HTTP/1.1 Authorization: Bearer {{token}} ### GET {{baseUrl}}/v1/namespaces/oss/metrics?list_parameters.filter=meta.name==package_version_scorecard and meta.parent_uuid== HTTP/1.1 Authorization: Bearer {{token}} ``` Below is an example response to the request. ```json expandable theme={null} [ { "category": "SCORE_CATEGORY_ACTIVITY", "centered_score": 6.956522, "description": "Captures the level of activity associated with the repository. Activity information is based on GitHub metadata. Higher levels of activity can mean that the repository is well maintained and will continue to be in the future.", "raw_score": 7.0212765, "score": 7 }, { "category": "SCORE_CATEGORY_POPULARITY", "centered_score": 8.076923, "description": "Captures how popular is the repository. Popularity information is based on GitHub metadata. Popular repositories are more likely to be maintained.", "raw_score": 7.368421, "score": 9 }, { "category": "SCORE_CATEGORY_CODE_QUALITY", "centered_score": 4.2105265, "description": "Provides a view of code quality and adherence to best practices in a repository. This information is based on from both GitHub metadata and the source code in the repository.", "raw_score": 4.848485, "score": 4 }, { "category": "SCORE_CATEGORY_SECURITY", "centered_score": 4.7297297, "description": "Captures the level of compliance with security best practices as well as vulnerability information for the repository including currently open as well as fixed vulnerabilities. Analysis only considers vulnerabilities associated with this repository and not its dependencies. Vulnerability information is based on OSV.dev data and Endor's vulnerability database", "raw_score": 8.333333, "score": 4 } ] ``` ## Get license text from a license finding 1. Look up a license-related **Finding** object for a dependency using the following filter: `spec.finding_categories contains [FINDING_CATEGORY_LICENSE_RISK] and spec.finding_tags not contains [FINDING_TAGS_SELF]` 2. Get the name of the corresponding **PackageVersion** object from the `spec.target_dependency_package_name` field. If we have a list of Finding objects, we can use the following `jq` command to get the PackageVersion name: `jq '.list.objects[].spec.target_dependency_package_name'` 3. Look up the PackageVersion object and store the UUID. > Note: If this is an OSS dependency we must use the "`oss`" namespace. 4. Look up the corresponding `pkg_version_info_for_license` **Metric** object using the following filter: `meta.name==pkg_version_info_for_license&meta.parent_uuid==$UUID` > Note: The Metric is in the same namespace as the PackageVersion. 5. Use the following `jq` command to extract the license text from the Metric object: `jq '.list.objects[].spec.metric_values.licenseInfoType.license_info.all_licenses[].matched_text'` For more information, see the [Metric resource kind documentation](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#metric). ```bash theme={null} # Get the target dependency PackageVersion name from a license-related finding NAME=$(endorctl api list --resource Finding \ --filter "spec.finding_categories contains [FINDING_CATEGORY_LICENSE_RISK] and spec.finding_tags not contains [FINDING_TAGS_SELF]" \ --page-size 1 \ | jq '.list.objects[].spec.target_dependency_package_name') # Get the target dependency PackageVersion uuid UUID=$(endorctl api list --resource PackageVersion \ --namespace oss \ --filter "meta.name==$NAME" \ | jq '.list.objects[].uuid') # Get the corresponding pkg_version_info_for_license Metric and extract the license text endorctl api list --resource Metric \ --namespace "oss" \ --filter "meta.name==pkg_version_info_for_license and meta.parent_uuid==$UUID" \ | jq '.list.objects[].spec.metric_values.licenseInfoType.license_info.all_licenses[].matched_text' ``` ```bash theme={null} # Get the target dependency PackageVersion name from a license-related finding NAME=$(curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=spec.finding_categories contains [FINDING_CATEGORY_LICENSE_RISK] and spec.finding_tags not contains [FINDING_TAGS_SELF]" \ --data-urlencode "list_parameters.page_size=1" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings \ | jq '.list.objects[].spec.target_dependency_package_name') # Get the target dependency PackageVersion uuid UUID=$(curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=meta.name==$NAME" \ https://api.endorlabs.com/v1/namespaces/oss/package-versions \ | jq '.list.objects[].uuid') # Get the corresponding pkg_version_info_for_license Metric and extract the license text curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=meta.name==pkg_version_info_for_license and meta.parent_uuid==$UUID" \ https://api.endorlabs.com/v1/namespaces/oss/metrics \ | jq '.list.objects[].spec.metric_values.licenseInfoType.license_info.all_licenses[].matched_text' ``` ## Get list of projects using a tool 1. Endor Labs stores CI/CD tool metrics in the `version_cicd_tools` **Metric** object, in the `spec.metric_values.CiCdTools.ci_cd_tools.tools` list. Use the following filter to get all such Metrics with entries for the given tool name (GitHub Actions in this example). For more information, see the [Metric resource kind documentation](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#metric). `meta.name==version_cicd_tools and spec.metric_values.CiCdTools.ci_cd_tools.tools.name=='GitHub Actions'` 2. Use the following `jq` command to get the UUIDs of the corresponding **Project** objects: `.list.objects[].spec.project_uuid` 3. Remove duplicate Project UUIDs (a Project can have multiple repository versions). 4. Use the UUIDs to get the corresponding Project objects. ```bash theme={null} # Get list of Project UUIDs PROJECT_UUIDS=$(endorctl api list --resource Metric \ --filter "meta.name==version_cicd_tools and spec.metric_values.CiCdTools.ci_cd_tools.tools.name=='GitHub Actions'" \ | jq -r '.list.objects[].spec.project_uuid') # Remove duplicate UUIDs UNIQUE_UUIDS=$(echo $PROJECT_UUIDS | sort | uniq) # Get Project for each uuid and extract the name for uuid in $UNIQUE_UUIDS do endorctl api get --resource Project --uuid $uuid | jq '.meta.name' done ``` ```bash theme={null} # Get list of Project UUIDs PROJECT_UUIDS=$(curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --data-urlencode "list_parameters.filter=meta.name==version_cicd_tools and spec.metric_values.CiCdTools.ci_cd_tools.tools.name=='GitHub Actions'" \ https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/metrics \ | jq -r '.list.objects[].spec.project_uuid') # Remove duplicate UUIDs UNIQUE_UUIDS=$(echo $PROJECT_UUIDS | sort | uniq) # Get Project for each uuid and extract the name for uuid in $UNIQUE_UUIDS do curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects/$uuid \ | jq '.meta.name' done ``` See also [List Projects, with Repository Versions and CI/CD Tool Metrics](/developers-api/rest-api/using-the-rest-api/advanced-use-cases/query-service#list-projects-with-repository-versions-and-cicd-tool-metrics) for a Query Service example that retrieves CI/CD tool Metrics for a list of projects. ## Get the latest scan result 1. To get the latest object, first sort the objects in descending order, based on the `meta.create_time` field: `list_parameters.sort.order=SORT_ENTRY_ORDER_DESC&list_parameters.sort.path=meta.create_time` 2. Then, to get only the latest object, set the page size to 1: `list_parameters.page_size=1` ```bash theme={null} endorctl api list --resource ScanResult \ --sort-order descending \ --sort-path meta.create_time \ --page-size=1 ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/scan-results?list_parameters.sort.order=SORT_ENTRY_ORDER_DESC&list_parameters.sort.path=meta.create_time&list_parameters.page_size=1" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/scan-results?list_parameters.sort.order=SORT_ENTRY_ORDER_DESC&list_parameters.sort.path=meta.create_time&list_parameters.page_size=1 HTTP/1.1 Authorization: Bearer {{token}} ``` ## Create a policy The following example uses the [Create Policy](/api-reference/policyservice/createpolicy) endpoint to create a new policy. ```bash theme={null} endorctl api create --resource Policy \ --data '{ "meta": { "description": "Disable action policies for CVE-2020-7677", "kind": "Policy", "name": "Ignore CVE-2020-7677" }, "propagate": true, "spec": { "exception": { "reason": "EXCEPTION_REASON_RISK_ACCEPTED" }, "policy_type": "POLICY_TYPE_EXCEPTION", "query_statements": [ "data.exceptions.match_finding" ], "resource_kinds": [ "Finding" ], "rule": "package exceptions\n\nmatch_finding[result] {\n\tsome i\n data.resources.Finding[i].spec.finding_metadata.vulnerability.spec.aliases[_] = \"CVE-2020-7677\"\n result = { \"Endor\" : { \"Finding\" : data.resources.Finding[i].uuid } }\n}" }, "tenant_meta": { "namespace": "$ENDOR_NAMESPACE" } }' ``` ```bash theme={null} curl --request POST \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies" \ --data '{ "meta": { "description": "Disable action policies for CVE-2020-7677", "kind": "Policy", "name": "Ignore CVE-2020-7677" }, "propagate": true, "spec": { "exception": { "reason": "EXCEPTION_REASON_RISK_ACCEPTED" }, "policy_type": "POLICY_TYPE_EXCEPTION", "query_statements": [ "data.exceptions.match_finding" ], "resource_kinds": [ "Finding" ], "rule": "package exceptions\n\nmatch_finding[result] {\n\tsome i\n data.resources.Finding[i].spec.finding_metadata.vulnerability.spec.aliases[_] = \"CVE-2020-7677\"\n result = { \"Endor\" : { \"Finding\" : data.resources.Finding[i].uuid } }\n}" }, "tenant_meta": { "namespace": "$ENDOR_NAMESPACE" } }' | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### POST {{baseUrl}}/v1/namespaces/{{namespace}}/policies HTTP/1.1 Authorization: Bearer {{token}} { "meta": { "name": "Detect Apache-2.0 License", "description": "Raise findings for dependencies using the Apache-2.0 license" }, "spec": { "policy_type": "POLICY_TYPE_USER_FINDING", "finding_level": "FINDING_LEVEL_CRITICAL", "finding": { "explanation": "One or more of the licenses associated with this package or package dependency violates organizational license policy.", "external_name": "License Compliance Violation", "level": "FINDING_LEVEL_CRITICAL", "remediation": "Please consult with legal for further instructions or to request an exception.", "summary": "Package uses the \"Apache-2.0\" license." }, "query_statements": [ "data.license.match_license" ], "resource_kinds": [ "Metric", "PackageVersion" ], "rule": "package license\n\nmatch_license[result] {\n some i\n data.resources.Metric[i]\n data.resources.Metric[i].meta.name == \"pkg_version_info_for_license\"\n data.resources.Metric[i].meta.parent_kind == \"PackageVersion\"\n lower(data.resources.Metric[i].spec.metric_values.licenseInfoType.license_info.all_licenses[_].name) == lower(\"Apache-2.0\")\n data.resources.PackageVersion[_].uuid == data.resources.Metric[i].meta.parent_uuid\n\n result = {\n \"Endor\": {\n \"PackageVersion\": data.resources.Metric[i].meta.parent_uuid,\n }\n }\n}" }, "tenant_meta": { "namespace": "{{namespace}}" } } ``` ## Update a policy to include a project The following example uses the [Update Policy](/api-reference/policyservice/updatepolicy) endpoint to apply a policy to a given project by updating the `spec.project_selector` tag list. This overrides the existing `project_selector` list, so you must pass in all the project inclusion tags that you want to keep for this policy along with the new tag. ```bash theme={null} endorctl api update --resource Policy --uuid \ --field-mask "spec.project_selector" \ --data '{ "spec" : { "project_selector" : [ "$uuid=" ] } }' ``` ```bash theme={null} curl --request PATCH \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies" \ --data '{ "request" : { "update_mask": "spec.project_selector" }, "object" : { "uuid" : "", "spec" : { "project_selector": [ "$uuid=" ] } } }' | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/policies HTTP/1.1 Authorization: Bearer {{token}} { "request" : { "update_mask": "spec.project_selector" }, "object" : { "uuid" : "", "spec" : { "project_selector": [ "$uuid=" ] } } } ``` ## Update a policy to exclude a project The following example uses the [Update Policy](/api-reference/policyservice/updatepolicy) endpoint to exclude a given project from a policy by updating the `spec.project_exceptions` tag list. This overrides the existing `project_exceptions` list, so you must pass in all project exception tags that you want to keep for this policy along with the new tag. ```bash theme={null} endorctl api update --resource Policy --uuid \ --field-mask "spec.project_exceptions" \ --data '{ "spec" : { "project_exceptions" : [ "$uuid=" ] } }' ``` ```bash theme={null} curl --request PATCH \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies" \ --data '{ "request" : { "update_mask": "spec.project_exceptions" }, "object" : { "uuid" : "", "spec" : { "project_exceptions": [ "$uuid=" ] } } }' | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/policies HTTP/1.1 Authorization: Bearer {{token}} { "request" : { "update_mask": "spec.project_exceptions" }, "object" : { "uuid" : "", "spec" : { "project_exceptions": [ "$uuid=" ] } } } ``` ## Update an exception policy to apply custom tags to matching findings The following example uses the [Update Policy](/api-reference/policyservice/updatepolicy) endpoint to specify a list of custom tags to apply to findings matching a given exception policy. This overrides the existing `spec.exception.tags` list, so you must pass in all tags that you want to keep for this policy along with the new tag. ```bash theme={null} endorctl api update --resource Policy --uuid \ --field-mask "spec.exception.tags" \ --data '{ "spec" : { "exception" : { "tags" : [ , ] } } }' ``` ```bash theme={null} curl --request PATCH \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies" \ --data '{ "request" : { "update_mask": "spec.exception.tags" }, "object" : { "uuid" : "", "spec" : { "exception": { "tags" : [ "", "" ] } } } }' | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/policies HTTP/1.1 Authorization: Bearer {{token}} { "request" : { "update_mask": "spec.exception.tags" }, "object" : { "uuid" : "", "spec" : { "exception": { "tags" : [ "", "" ] } } } } ``` ## Upgrade a policy to use the latest template version The following example uses the [Update Policy](/api-reference/policyservice/updatepolicy) endpoint to upgrade a given policy to use the latest template version. ```bash theme={null} endorctl api update --resource Policy --uuid \ --field-mask "spec.template_version" \ --data '{ "spec" : { "template_uuid" : "", "template_version" : "2.0.0" } }' ``` ```bash theme={null} curl --request PATCH \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies" \ --data '{ "request" : { "update_mask": "spec.template_version" }, "object" : { "uuid" : "", "spec" : { "template_uuid" : "", "template_version" : "2.0.0" } } }' | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/policies HTTP/1.1 Authorization: Bearer {{token}} { "request" : { "update_mask": "spec.template_version" }, "object" : { "uuid" : "", "spec" : { "template_uuid" : "", "template_version" : "2.0.0" } } } ``` ## Delete a policy The following example uses the [Delete Policy](/api-reference/policyservice/deletepolicy) endpoint to delete a policy. ```bash theme={null} endorctl api delete --resource Policy --uuid ``` ```bash theme={null} curl --request DELETE \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies/" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### DELETE {{baseUrl}}/v1/namespaces/{{namespace}}/policies/ HTTP/1.1 Authorization: Bearer {{token}} ``` ## Add meta tags to an object The following example uses the [Update Finding](/api-reference/findingservice/updatefinding) endpoint to add custom tags to a finding by updating the `meta.tags` field. This overrides the existing `meta.tags` list, so you must pass in all tags that you want to keep for this object along with the new tag. ```bash theme={null} endorctl api update --resource Finding --uuid \ --field-mask "meta.tags" \ --data '{ "meta" : { "tags" : [ "tag1", "tag2", "tag3" ] } }' ``` ```bash theme={null} curl --request PATCH \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings" \ --data '{ "request" : { "update_mask": "meta.tags" }, "object" : { "uuid" : "", "meta" : { "tags": [ "tag1", "tag2", "tag3" ] } } }' | jq '.' ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/findings HTTP/1.1 Authorization: Bearer {{token}} { "request" : { "update_mask": "meta.tags" }, "object" : { "uuid" : "", "meta" : { "tags": [ "tag1", "tag2", "tag3" ] } } } ``` ## Get data from child namespaces Use the `traverse` option to include data from child namespaces as well as the parent namespace. ```bash theme={null} endorctl api list --resource Project --traverse ``` ```bash theme={null} curl --get \ --header "Authorization: Bearer $ENDOR_TOKEN" \ --compressed \ --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects?list_parameters.traverse=true" ``` ```bash theme={null} @baseUrl = https://api.endorlabs.com @token = @namespace = ### GET {{baseUrl}}/v1/namespaces/{{namespace}}/projects?list_parameters.traverse=true HTTP/1.1 Authorization: Bearer {{token}} ``` # Research Open Source Risks Source: https://docs.endorlabs.com/discover/index Open-source packages are invaluable as they not only reduce costs but also foster community-driven improvements, enabling users to customize solutions to fit specific needs. By discovering these open-source frameworks, users can tap into a wealth of resources to enhance their projects, streamline workflows, and contribute to the broader open-source community. Endor Labs Vulnerability Database is a comprehensive database of vulnerabilities in open-source packages. It is updated daily and provides a wealth of information on vulnerabilities. The following sections provide information on how to discover open-source packages and vulnerabilities. Search for open source packages by their ecosystem. Search for vulnerabilities in open source packages. Search and evaluate AI models from Hugging Face with security, activity, and quality scores. # Search for Open Source Packages Source: https://docs.endorlabs.com/discover/open-source-packages/index Open source packages provide flexible, customizable software solutions that can reduce development costs and time, while also fostering innovation through community collaboration. To search for open source packages: 1. Select **Discovery** > **Open Source Packages** from the left sidebar. 2. Type in the search bar to look for open source packages and click **Search Open Source Packages**. Open source packages search and list 3. Select a search result to view more details. 4. Choose the **Ecosystem** and click **Search Open Source Packages** to look for packages by their ecosystem. 5. Review the list of package versions, their dependencies, and Endor security scores. OSS packages table # Endor Labs Vulnerability Database Source: https://docs.endorlabs.com/discover/vulnerability-db/index Understand how to search, analyze, and navigate vulnerabilities. A vulnerability is a security weakness in a software package that attackers can exploit to compromise systems, steal data, or disrupt operations. Open-source software often contains vulnerabilities that can introduce risks to your organization, if not managed properly. Endor Labs vulnerability database is a comprehensive compilation of known software vulnerabilities. You can search the vulnerability database to identify and discover vulnerabilities within your software dependencies. You can use the following vulnerability IDs to search within the Endor Labs platform: Endor Labs supports vulnerability searches only for identifiers included in the `meta.name` or `spec.aliases` fields. ## Search for a vulnerability Search for vulnerabilities using supported security identifiers across your software dependencies. 1. Select **Discovery** from the left sidebar. 2. Select **Vulnerabilities**. 3. Type a search query using a vulnerability ID, for example, CVE, GHSA, and click **Search Vulnerabilities**. Vulnerability Search You can view detailed information including the name of the vulnerability, CVE ID, vulnerability's severity, description, and metadata to help users quickly identify important details about a vulnerability. 4. Select **Affected Packages** to view a list of all software packages impacted by the identified vulnerability, including their names, introduced and fixed versions, and the source of the vulnerability data. 5. Select a package to view its details. * **Overview**: Shows affected and fixed versions, severity, available patches, impacted classes, and a link to the fix commit. It helps users understand the issue and take necessary remediation steps. Affected packages overview * **Endor Details**: Shows affected call paths and file paths to help identify where the vulnerable code runs and what can trigger it in the project Affected Packages details * **Impact**: Shows each package version, along with the number of findings, how many projects use it, and how many other packages depend on it Affected Packages Impact 6. Select **Containers** to see all container images in your organization with known vulnerabilities. It lists the affected packages, where each issue entered, whether fixes are available, and the severity of the issues. affected packages container # About Endor Labs Source: https://docs.endorlabs.com/index Endor Labs is a unified application security platform that helps you ship secure code by default, whether humans or agents write the code. We address your software security needs with the following key features: * **Unified platform:** A single platform for SAST, secrets detection, SCA, malicious package detection, [Package Firewall](/package-firewall), [Coding Agent Governance](/agent-governance), and container scanning. * **Prioritization & noise reduction:** Reachability analysis cuts through the noise by identifying which vulnerabilities actually affect your code. * **Fix, not just find:** Go beyond detection with actionable remediation guidance, upgrade impact analysis, and automated patching. * **Embrace AI confidently:** Discover AI models in your codebase, govern their usage, and leverage AI-powered assistance for security analysis and code fixes. Ready to go? Start your journey with Endor Labs and begin your first project scan. Connect the Endor Labs docs to your AI tools and get accurate answers about Endor Labs in Cursor, VS Code, Claude, and more. ## How Endor Labs works Endor Labs provides a prescriptive, outcome-focused workflow that guides you from initial setup to continuous security improvement. Automatically discover dependencies, vulnerabilities, secrets, and AI models across your entire codebase with a single integration. Cut through the noise with reachability analysis and risk scoring. Focus only on the vulnerabilities that actually impact your application. Fix issues faster with AI-powered remediation, upgrade impact analysis, and automated patching, not just alerts. ## Your journey with Endor Labs ## What makes us different The Endor Labs platform blends advanced static analysis techniques, meticulous research, and thoughtful AI use to surface relevant, reliable threats and actionable remediations. Granular policies combined with a suite of integrations help you control risk across your SDLC. Endor Labs provides AI-powered developer assistance to identify and help you fix vulnerabilities in your code. Endor Labs analyzes your first-party code, software packages, and containers to provide context on how attackers could exploit each vulnerability in your application. Endor Labs collects and analyzes a large amount of metadata about AI models and open-source packages and uses it to compute risk scores. Endor Labs inventories the AI coding agents, MCP servers, and skills your developers use, and enforces policies on risky agent actions in real time. Endor Labs blocks known-malicious packages and controls package installations in real time, before they reach developer machines or CI. Endor Labs policies give you control of risk in your environment. When combined with integrations into platforms like GitHub and GitLab, you can choose which risks to block and which to flag as warnings. Understand Endor Labs licensing, SKUs, per-seat scan credit allocations, and fair-usage limits. # Export findings to GitHub Advanced Security Source: https://docs.endorlabs.com/integrations/data-exporters/export-to-ghas/index Learn how to export findings to GitHub Advanced Security. You can export the findings generated by Endor Labs to GitHub Advanced Security so that you can view the findings in the GitHub. Endor Labs exports the findings in the SARIF format and uploads them to GitHub. You can view the findings under **Security** > **Vulnerability Alerts** > **Code Scanning** in GitHub. GitHub has multiple limitations for SARIF files, so you may not be able to experience the full benefits on Endor Labs. For example, GitHub limits the number of results in a SARIF file. It allows a maximum of 25000 results per file but displays the first 5000 results ranked by severity. Refer to [GitHub SARIF support for code scanning](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#validating-your-sarif-file) for the complete list of SARIF file limitations in GitHub Advanced Security. ## Prerequisites Ensure that you meet the following prerequisites before exporting findings to GitHub Advanced Security: * Endor Labs GitHub App (Pro) installed in your GitHub repository. See [Deploy Endor Labs GitHub App (Pro)](/setup-deployment/scm-integrations/github-app-pro) for more information. * Turn on code scanning in your GitHub repository. Refer to [Enabling code scanning](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) for more information. * Download and install endorctl. See [Install endorctl](/introduction/getting-started) for more information. ## Create a GHAS SARIF exporter GHAS SARIF exporter allows you to export the findings generated by Endor Labs in the SARIF format. See [Understanding SARIF files](/scan/sca/scanning-strategies#understand-sarif-files) for more information on the SARIF format and Endor-specific extensions. You can create a GHAS SARIF exporter using the Endor Labs API. Run the following command to create a GHAS SARIF exporter. ```bash expandable theme={null} endorctl api create -n -r Exporter -d '{ "meta": { "name": "" }, "tenant_meta": { "namespace": "" }, "spec": { "exporter_type": "EXPORTER_TYPE_GHAS", "message_type_configs": [ { "message_type": "MESSAGE_TYPE_FINDING", "message_export_format": "MESSAGE_EXPORT_FORMAT_SARIF" } ] }, "propagate": true }' ``` For example, to create a GHAS SARIF exporter named `ghas-exporter` in the namespace `doe.deer`, run the following command. ```bash expandable theme={null} endorctl api create -n doe.deer -r Exporter -d '{ "meta": { "name": "ghas-exporter" }, "tenant_meta": { "namespace": "doe.deer" }, "spec": { "exporter_type": "EXPORTER_TYPE_GHAS", "message_type_configs": [ { "message_type": "MESSAGE_TYPE_FINDING", "message_export_format": "MESSAGE_EXPORT_FORMAT_SARIF" } ] }, "propagate": true }' ``` ## Configure scan profile and project to use the GHAS SARIF exporter You can configure the scan profile to use the GHAS SARIF exporter and associate it with your project. You can also set the scan profile as the default scan profile so that all the projects in the namespace use the scan profile by default. See [Scan profiles](/scan/scan-profiles) for more information. ### Configure the scan profile Ensure that you select the GHAS SARIF exporter in the **Export** section of the scan profile. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Scan Profiles**. 3. Select the scan profile you want to configure and click **Edit Scan Profile**. 4. Select the GHAS SARIF exporter under **Exporters** and click **Save Scan Profile**. Scan profile ### Configure the project to use the scan profile Ensure that you choose the scan profile with the GHAS SARIF exporter for the project. 1. Go to the **Projects** page and select the project you want to configure. 2. Select **Settings** and select the scan profile you want to use under **Scan Profile**. Scan profile for projects ## Scan projects to use the GHAS SARIF exporter After the configuration is complete, your subsequent scans will export the findings in the SARIF format and upload them to GitHub. You can rescan the project immediately instead of waiting for the next scheduled scan. See [Rescan projects](/setup-deployment/scm-integrations/github-app/re-scan-projects) for more information. If you have enabled pull request scans in your GitHub App, the GHAS SARIF exporter exports the findings for each pull request. ## View findings in GitHub 1. Navigate to your GitHub repository. 2. Select **Security**. 3. Select **Code scanning** under **Vulnerability Alerts**. View findings in GitHub You can use the search bar to filter the findings. You can also view findings for a specific branch and other filter criteria. You can also view the findings specific to a pull request if you have enabled pull request scans. You can filter the findings by the pull request number and view findings associated with the pull request. You can select a finding and view the commit history behind the finding. Filter findings in GitHub 4. Select **Campaigns** to view and create security campaigns that coordinate remediation efforts across multiple repositories. See [GitHub security campaign](/best-practices/github-security-campaign) for more information. ### Filter findings by tags in GitHub After you export findings to GHAS, Endor Labs includes finding tags and categories as searchable tags in the SARIF output. These tags appear in the GitHub code scanning interface, and you can filter and identify specific types of findings. Endor Labs exports the following types of tags to GHAS: * **Finding tags**: System-defined attributes such as `REACHABLE_FUNCTION`, `FIX_AVAILABLE`, `EXPLOITED, DIRECT`, `TRANSITIVE`, and others. See [Finding tags](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#finding-tags) for the complete list. * **Finding categories**: Categories such as `SCA`, `SAST`, `VULNERABILITY`, `SECRETS`, `CONTAINER`, `CICD`, `GHACTIONS`, `LICENSE_RISK`, `MALWARE`, `OPERATIONAL`, `SCPM`, `SECURITY`, `SUPPLY_CHAIN`, and `AI_MODELS`. See [Finding categories](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#finding-categories) for the complete list. You can use the search bar to filter findings by tags. Use the tag: prefix followed by the tag name to search for specific Endor Labs tags. You can combine multiple filters to narrow down your results. For example, to find reachable vulnerabilities with available fixes: ``` tag:REACHABLE_FUNCTION tag:FIX_AVAILABLE ``` Filter findings by tags in GitHub ### Filter findings exported to GitHub You can control which findings you export to GHAS by using action policies. Only findings from projects within the scope of your configured action policies reach GitHub Advanced Security. To filter findings using action policies: 1. Create an [action policy](/platform-administration/policies/action-policies) that defines the criteria for findings you want to export, or use an existing action policy. 2. Assign specific projects to the scope of the action policy you want to use. 3. Run the following command to create a GHAS SARIF exporter that exports only findings from projects in the scope of your action policies. Use `MESSAGE_TYPE_ADMISSION_POLICY_FINDING` as the `message_type` to filter findings based on your action policies. ```bash theme={null} endorctl api create -n -r Exporter -d '{ "meta": { "name": "" }, "tenant_meta": { "namespace": "" }, "spec": { "exporter_type": "EXPORTER_TYPE_GHAS", "message_type_configs": [ { "message_type": "MESSAGE_TYPE_ADMISSION_POLICY_FINDING", "message_export_format": "MESSAGE_EXPORT_FORMAT_SARIF" } ] }, "propagate": true }' ``` # Export findings to S3 Source: https://docs.endorlabs.com/integrations/data-exporters/export-to-s3/index Learn how to export findings and scan data to an AWS S3 storage bucket using the Endor Labs export framework. Export scan data generated by Endor Labs to an AWS S3 storage bucket. This enables long-term data retention for compliance requirements, integration with security information and event management (SIEM) systems, and custom analytics workflows. The export framework supports exporting findings in JSON or SARIF format, allowing flexible integration with your existing toolchain. Amazon S3 is an object storage service provided by Amazon Web Services (AWS). It offers high durability, availability, and scalability for storing and retrieving any amount of data. S3 integrates with other AWS services and third-party tools, making it ideal for data archival, backup, and analytics workflows. ## Prerequisites Ensure that you meet the following prerequisites before exporting data to S3: * An AWS account with permissions to create IAM roles, identity providers, and S3 buckets. * An S3 bucket to store the exported data. See [Create an S3 bucket](#create-an-s3-bucket). * An OIDC identity provider configured to allow Endor Labs access. See [Add an OIDC identity provider](#1-add-an-oidc-identity-provider). * An IAM role with permissions for Endor Labs to write to your S3 bucket. See [Create an IAM role](#2-create-an-iam-role). * Download and install endorctl. See [Install endorctl](/introduction/getting-started). ## Create an S3 bucket An S3 bucket is a container for storing objects in Amazon S3. Each bucket has a globally unique name, and you create it in a specific AWS region. You can create a general purpose S3 bucket or reuse an existing bucket to store the exported data. Disable access control lists (ACLs) on the bucket so IAM policies and bucket policies control access, preventing unintended public access. Refer to [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) for detailed instructions on creating an S3 bucket. S3 buckets #### Configure bucket lifecycle You can configure S3 lifecycle rules to automatically delete exported data after a specified retention period. Exported objects do not expire unless you configure lifecycle rules. 1. In the AWS management console, navigate to **Amazon S3** > **Buckets**. 2. Select your bucket. 3. Select **Management** and click **Create lifecycle rule**. 4. Enter a **Lifecycle rule name**, for example, `endor-exports-expiry`. 5. Under **Filter type**, select **Limit the scope of this rule using one or more filters** and enter `endor/` as the prefix to apply the rule only to exported data. 6. Under **Lifecycle rule actions**, select **Expire current versions of objects**. 7. Under **Expire current versions of objects**, enter the number of days after which S3 deletes objects. 8. Review the rule and click **Create rule**. ## Configure access for Endor Labs Endor Labs uses OIDC federation to assume an IAM role in your AWS account to access the S3 bucket. To allow Endor Labs to write to the bucket, configure OIDC and IAM using one of the following methods: * Use the [CFT template](#create-aws-resources-using-a-cft-template) to create the OIDC identity provider, IAM role, and S3 write policy. * Use the [AWS Management console](#create-access-through-the-console) to create access by adding the OIDC identity provider and IAM role. ### Create AWS resources using a CFT template Use an AWS CloudFormation Template (CFT) to create the IAM role and S3 `PutObject` policy for the S3 exporter. The template can create a new OIDC identity provider for Endor Labs or reuse an existing provider in your account. The following table lists the parameters you can set when deploying the CFT template. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. 1. Create a `.cft` file with the following template. You can use the following template and set the parameters according to your OIDC audience, tenant namespace, bucket name, role name, and optionally an existing OIDC provider ARN. ```yaml expandable theme={null} AWSTemplateFormatVersion: "2010-09-09" Description: > Endor Labs S3 Exporter - creates IAM OIDC provider (optional), role, and minimal S3 PutObject policy. Parameters: OIDCUrl: Type: String Default: "https://api.endorlabs.com" Description: "Endor Labs OIDC issuer URL." ExistingOidcProviderArn: Type: String Default: "" Description: > Optional. If your AWS account already has an OIDC provider for https://api.endorlabs.com, set this to its ARN (for example, arn:aws:iam:::oidc-provider/api.endorlabs.com). When set, this template will NOT create a new OIDC provider. It will reuse the existing provider and ensure the OidcAudience is present in its ClientIdList. OidcAudience: Type: String Default: "s3-exporter" Description: "Specify the audience name to use in the OIDC trust policy. Set the same value in allowed_audience while creating the Endor exporter configuration." TenantNamespace: Type: String Description: "Root Endor Labs tenant namespace (for example, acme-corp)." BucketName: Type: String Description: "Existing S3 bucket name to receive exports." RoleName: Type: String Default: "EndorS3ExporterRole" Description: "IAM role name Endor will assume via web identity." PolicyName: Type: String Default: "EndorS3ExporterPolicy" Description: "IAM managed policy name for S3 PutObject permission." Conditions: CreateOidcProvider: !Equals [!Ref ExistingOidcProviderArn, ""] UseExistingOidcProvider: !Not [!Equals [!Ref ExistingOidcProviderArn, ""]] Resources: EndorOidcProvider: Type: AWS::IAM::OIDCProvider DeletionPolicy: Delete UpdateReplacePolicy: Delete Condition: CreateOidcProvider Properties: Url: !Ref OIDCUrl ClientIdList: - !Ref OidcAudience EndorS3PutObjectPolicy: Type: AWS::IAM::ManagedPolicy DeletionPolicy: Delete UpdateReplacePolicy: Delete Properties: ManagedPolicyName: !Ref PolicyName PolicyDocument: Version: "2012-10-17" Statement: - Sid: PutObjectToBucket Effect: Allow Action: - s3:PutObject Resource: !Sub "arn:${AWS::Partition}:s3:::${BucketName}/*" EndorS3ExporterRole: Type: AWS::IAM::Role DeletionPolicy: Delete UpdateReplacePolicy: Delete Properties: RoleName: !Ref RoleName AssumeRolePolicyDocument: Version: "2012-10-17" Statement: - Sid: EndorWebIdentity Effect: Allow Principal: Federated: !If - CreateOidcProvider - !Ref EndorOidcProvider - !Ref ExistingOidcProviderArn Action: sts:AssumeRoleWithWebIdentity Condition: StringEquals: "api.endorlabs.com:aud": !Ref OidcAudience StringLike: "api.endorlabs.com:sub": - !Sub "${TenantNamespace}/*" - !Sub "${TenantNamespace}.*/*" ManagedPolicyArns: - !Ref EndorS3PutObjectPolicy Outputs: OidcProviderArn: Description: "OIDC provider ARN." Value: !If - CreateOidcProvider - !Ref EndorOidcProvider - !Ref ExistingOidcProviderArn RoleArn: Description: "Role ARN to set as assume_role_arn in Endor exporter config." Value: !GetAtt EndorS3ExporterRole.Arn OidcAudienceOut: Description: "Audience to set as allowed_audience in Endor exporter config." Value: !Ref OidcAudience ``` 2. Save this file with an appropriate name such as `endorlabs-s3-export.cft`. 3. Sign into AWS CloudFormation and search for **Stacks**. 4. Click **Create Stack** and select **With new resources**. 5. From **Template source**, select **Upload a template file**. 6. Click **Choose file**, select the file you saved, and click **Next**. 7. In **Specify stack details**, enter a **Stack name**, verify the **Parameters** you entered in the script and click **Next**. 8. Select the acknowledgement from **Configure stack options** and click **Next**. 9. From **Review and Create**, review the details and click **Submit**. Check the progress of the creation of your resources from **Stacks**. After AWS creates the stack, you can see the status as **CREATE\_COMPLETE**. ### Create access through the Console Create the OIDC identity provider and IAM role manually in the AWS Management Console. #### 1. Add an OIDC identity provider OpenID Connect (OIDC) federation allows Endor Labs to access AWS resources without requiring long-lived credentials. This reduces the risk of credential exposure and simplifies secret rotation. 1. In the AWS management console, navigate to **IAM** > **Access Management** > **Identity providers**. 2. Click **Add provider**. 3. Under **Provider details**, select **OpenID Connect**. 4. For **Provider URL**, enter `https://api.endorlabs.com`. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. 5. For **Audience**, specify a unique identifier to validate incoming OIDC tokens from Endor Labs. 6. Optionally, add tags to help identify the provider. 7. Click **Add provider**. Create identity provider #### 2. Create an IAM role Create an IAM role that Endor Labs can assume to write to your S3 bucket. This involves: 1. [Create a permissions policy](#create-a-permissions-policy): Define the S3 write permissions. 2. [Create an IAM role](#create-the-iam-role): Create a role with OIDC trust and attach the policy. #### Create a permissions policy 1. In the AWS management console, navigate to **IAM** > **Access Management** > **Policies**. 2. Click **Create policy**. 3. Under **Specify permissions**, toggle the **Policy editor** to **JSON**. 4. Enter the following policy: ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": "arn:aws:s3:::/*" } ] } ``` Replace `` with the name of your S3 bucket. 5. Click **Next**. 6. Under **Review and create**, enter a **Policy name**. For example, `EndorLabsS3ExportPolicy`. 7. Review the **Permissions defined in this policy section** to confirm that this policy lists the expected Amazon S3 write actions. 8. Optionally, add a description and tags to your policy. 9. Click **Create policy**. Policy permissions #### Create an IAM role 1. In the AWS management console, navigate to **IAM** > **Access Management** > **Roles**. 2. Click **Create role**. 3. Under **Select trusted entity**, select **Custom trust policy**. 4. Enter the following trust policy: If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ```json expandable theme={null} { "Version": "2012-10-17", "Statement": [ { "Sid": "EndorWebIdentity", "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam:::oidc-provider/api.endorlabs.com" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "api.endorlabs.com:aud": "" }, "StringLike": { "api.endorlabs.com:sub": [ "/*", ".*" ] } } } ] } ``` Replace the placeholders with your values: * ``: Your AWS account ID * ``: The audience value you configured in the OIDC provider * ``: Your Endor Labs namespace Create IAM role 5. Click **Next**. 6. Under **Add permissions**, search for and select the IAM policy you created. IAM role permissions 7. Click **Next**. 8. Under **Name, review, and create**, enter a **Role name** for the S3 exporter role. For example, `EndorLabsS3ExporterRole`. IAM role name 9. Optionally, add tags to help identify the role. 10. Click **Create role**. ## Create an S3 exporter Create an S3 exporter using the Endor Labs API to configure the export destination and data types. The following table lists the configuration options required to create the exporter. Run the following command to create an S3 exporter. ```bash expandable theme={null} endorctl api create \ --namespace= \ --resource=Exporter \ --data '{ "meta": { "name": "" }, "propagate": true, "spec": { "exporter_type": "EXPORTER_TYPE_S3", "s3_config": { "bucket_name": "", "region": "", "assume_role_arn": "", "allowed_audience": "" }, "message_type_configs": [ { "message_type": "MESSAGE_TYPE_FINDING", "message_export_format": "MESSAGE_EXPORT_FORMAT_JSON" } ] } }' ``` For example, to create an S3 exporter named `s3-findings-exporter` in the namespace `doe.deer` that exports findings in JSON format, run the following command. ```bash expandable theme={null} endorctl api create \ --namespace=doe.deer \ --resource=Exporter \ --data '{ "meta": { "name": "s3-findings-exporter" }, "propagate": true, "spec": { "exporter_type": "EXPORTER_TYPE_S3", "s3_config": { "bucket_name": "my-endorlabs-exports", "region": "us-west-2", "assume_role_arn": "arn:aws:iam::123456789012:role/EndorLabsS3ExportRole", "allowed_audience": "s3-exporter" }, "message_type_configs": [ { "message_type": "MESSAGE_TYPE_FINDING", "message_export_format": "MESSAGE_EXPORT_FORMAT_JSON" } ] } }' ``` ## Configure scan profile to use the S3 exporter After creating the exporter, associate it with your scan profile. You can also set the scan profile as the default for your namespace so all projects use it automatically. See [Scan profiles](/scan/scan-profiles) for more information. ### Configure the scan profile 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Scan Profiles**. 3. Select the scan profile you want to configure and click **Edit Scan Profile**. 4. Select your exporter under **Exporters** and click **Save Scan Profile**. ### Configure the project to use the scan profile Associate your project with a scan profile to enable automatic export of scan data. 1. Select **Projects** from the left sidebar and select the project you want to configure. 2. Select **Settings** and select the scan profile you want to use under **Scan Profile**. ## Scan projects to export data After configuration, subsequent scans automatically export data to your S3 bucket. You can trigger a rescan immediately. See [Rescan projects](/setup-deployment/scm-integrations/github-app/re-scan-projects) for more information. To validate that the S3 exporter ran successfully for a scan: 1. Select **Projects** from the left sidebar and select the project associated with your exporter. 2. Select **Scan History** and select a record to view its information. 3. Select **Logs** to view the scan log and set the log level to **All** The following message confirms that the S3 export is successful. `INFO: Successfully completed S3 export` ### Exported file structure Endor Labs exports data to S3 using a hierarchical folder structure: ```text theme={null} endor/ └── -/ └── / └── -/ └── / └── / └── _.zip ``` The following table explains each path segment: #### Example file path ```text theme={null} my-bucket/endor/abc123-prod-exporter/acme-corp/6efgh-pythonrepo/schedule/main/20251215T143025Z_xyz789.zip ``` ## Manage the S3 exporter You can list, update, and delete S3 exporters using the Endor Labs API. Run the following command to list all exporters in your namespace. ```bash theme={null} endorctl api list --namespace= --resource=Exporter ``` Run the following command to update an existing exporter. Use the `--field-mask` parameter to specify the fields to update. ```bash theme={null} endorctl api update \ --namespace= \ --resource=Exporter \ --name= \ --field-mask "spec.s3_config.region" \ --data '{ "spec": { "s3_config": { "region": "us-west-2" } } }' ``` You must dissociate the exporter from any linked scan profiles before deletion. Run the following command to delete an exporter. ```bash theme={null} endorctl api delete --namespace= --resource=Exporter --name= ``` # Export findings to Wiz Source: https://docs.endorlabs.com/integrations/data-exporters/export-to-wiz/index Learn how to export findings from Endor Labs to Wiz to enable code-to-cloud correlation in the Wiz Security Graph. Endor Labs provides a holistic view of your code and software supply chain security so you can focus on the findings that matter most. Endor Labs pushes findings to Wiz after every scheduled scan on the default branch and maps them to Wiz’s enrichment schemas. Export findings from Endor Labs to Wiz by establishing a secure connection with Wiz API endpoints. The integration sends SCA and SAST findings identified during repository scans to Wiz, and Wiz ingests them into the Wiz Security Graph. **Branch restrictions** Wiz exports apply only to the default branch. Currently, you cannot export pull request scans and non-default branch scans. ## Prerequisites Ensure that the following prerequisites are complete: * To use the Endor Labs integration, your Wiz tenant must have the **Wiz Code License**. * Connect your source code manager to Wiz so that Wiz scans repositories and findings become available. Wiz currently supports the following providers: * GitHub * GitLab * Bitbucket * Azure DevOps This connection ensures that `REPOSITORY_BRANCH` assets exist in Wiz's inventory. Without this connection, Wiz accepts findings but **SKIPS** them during ingestion because Wiz cannot resolve the repository. * Add the [Endor Labs integration](https://app.wiz.io/settings/automation/integrations) from the Wiz Integration Network. When you create the integration, Wiz shows the required API scopes for the service account. Save the following values because you will need them when creating the Wiz exporter in Endor Labs: * Client ID * Client Secret * API Endpoint URL * Authentication URL * Download and install endorctl. See [Install endorctl](/introduction/getting-started). ## Create a Wiz exporter Create a Wiz exporter with the Endor Labs API to configure the export destination and data types. The following table lists the configuration options required to create the exporter. Run the following command to create a Wiz exporter. ```bash expandable theme={null} endorctl api create \ --namespace= \ --resource=Exporter \ --data '{ "meta": { "name": "" }, "propagate": true, "spec": { "exporter_type": "EXPORTER_TYPE_WIZ", "wiz_config": { "api_endpoint_url": "", "oauth_client_credentials": { "auth_endpoint_url": "", "client_id": "", "client_secret": "" } }, "message_type_configs": [ { "message_type": "MESSAGE_TYPE_FINDING", "message_export_format": "MESSAGE_EXPORT_FORMAT_JSON" } ] } }' ``` For example, to create a Wiz exporter named `wiz-findings-export` in the namespace `doe.deer` that exports findings to Wiz: ```bash expandable theme={null} endorctl api create \ --namespace=doe.deer \ --resource=Exporter \ --data '{ "meta": { "name": "wiz-findings-export" }, "propagate": true, "spec": { "exporter_type": "EXPORTER_TYPE_WIZ", "wiz_config": { "api_endpoint_url": "https://api.us18.app.wiz.io/graphql", "oauth_client_credentials": { "auth_endpoint_url": "https://auth.app.wiz.io/oauth/token", "client_id": "your-wiz-client-id", "client_secret": "your-wiz-client-secret" } }, "message_type_configs": [ { "message_type": "MESSAGE_TYPE_FINDING", "message_export_format": "MESSAGE_EXPORT_FORMAT_JSON" } ] } }' ``` ## Configure the scan profile to use the Wiz exporter After creating the exporter, associate it with your scan profile. You can also set the scan profile as the default for your namespace so all projects use it automatically. See [Scan profiles](/scan/scan-profiles) for more information. ### Configure the scan profile 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Scan Profiles**. 3. Select the scan profile you want to configure and click **Edit Scan Profile**. 4. Select your exporter under **Exporters** and click **Save Scan Profile**. ### Configure the project to use the scan profile Associate your project with a scan profile to enable automatic export of scan data. 1. Select **Projects** from the left sidebar and select the project you want to configure. 2. Select **Settings** and select the scan profile you want to use under **Scan Profile**. ## View findings in Wiz Once Wiz successfully ingests findings, you can view them directly in the Wiz **Findings** dashboard. Wiz correlates these findings with your cloud assets and repositories in the Wiz Security Graph. You can filter by origin to easily locate findings from Endor Labs. ## Finding lifecycle in Wiz Endor Labs exports findings to Wiz after every scheduled scan on the default branch. Wiz manages finding state based on data sources: * **Full state snapshot**: Each upload represents the complete current state of findings for a project and branch. Wiz treats it as a full replacement. * **Upload limit**: Wiz allows up to three uploads per branch per day. Wiz may not process additional uploads for the same branch within 24 hours. * **Automatic resolution**: If a finding was present in a previous upload but is absent in the current upload for the same scope, Wiz automatically marks it as resolved and closes any associated Wiz Issues. * **Staleness**: Findings not refreshed within 7 days are automatically removed by Wiz. Wiz recommends uploading at least every 24 hours to align with their scanning cycle. ## Ingestion status When an upload completes, Wiz processes the results asynchronously. The following table lists the ingestion outcomes. Even when the system activity status is SUCCESS, Wiz ingests the payload at its own pace. We recommend waiting up to 24 hours for findings to appear in Wiz. ## FAQs Wiz links findings only to existing `REPOSITORY_BRANCH` assets in Wiz. Connect the SCM to Wiz so that repositories exist in Wiz's inventory. If the repository is not connected to Wiz, the upload succeeds but Wiz skips the ingestion of the upload. No, this is a one-way integration that only supports pushing findings from Endor Labs to Wiz. Wiz automatically removes findings that are not refreshed within seven days. To keep your findings current, schedule scans to run regularly. Wiz limits uploads to a maximum of three per branch per day. Even when the system activity status is `SUCCESS`, Wiz ingests the payload at its own pace. We recommend waiting up to 24 hours for findings to reflect in Wiz. Endor Labs exports findings to Wiz only from the repository’s default branch. Scans on other branches do not export findings to Wiz. # Data exporters Source: https://docs.endorlabs.com/integrations/data-exporters/index Learn how to export findings and scan data from Endor Labs to external storage and security platforms using the export framework. Endor Labs provides an export framework that enables you to export scan data to external platforms for archival, compliance, or integration with other security tools. You can configure exporters to automatically send data to supported destinations after each scan. ## Supported export destinations The export framework supports the following destinations. ## Supported data types You can configure exporters to export different types of data: ## Supported export formats # Set up email integration Source: https://docs.endorlabs.com/integrations/email/index Learn how to integrate your email addresses with Endor Labs and receive finding notifications Integrate your email address with Endor Labs and automatically receive policy violations as email notifications. * [Configure email integration](#configure-email-integration) * [Associate an action policy with the email notification](#associate-an-action-policy-with-the-email-notification) * [Customize email notification templates](#customize-email-notification-templates) * [Data model](#data-model) * [Run a scan](#run-a-scan) ## Configure email integration To configure an email integration, follow these steps: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Add** on the **Email** card. If you already have an email integration, click **Manage** instead. 3. Click **Add Notification Integration** to open the **Send Notifications to Email** dialog. 4. Enter a **Name** and **Description** for this integration. 5. In **Email addresses**, enter up to eight email addresses separated by commas. 6. Optional: select **Propagate this notification target to all child namespaces** to make this integration available in child namespaces. 7. Click **Add Notification Integration** to save the integration. ### Associate an action policy with the email notification Users can create action policies to send an email notification when a scan matches policy conditions. For example, if there is a critical or high vulnerability, send an email notification. To send an email when a scan produces matching findings, create an action policy with a **Send Notification** action that targets your email integration. For the full procedure, see [Create an action policy](/platform-administration/policies/action-policies). The email-specific choices are: * Under **Choose an Action**, select **Send Notification**. * From **Select notification targets**, choose the email integration you created. From **Select aggregation type**, choose how findings are grouped into notifications. * **None (Notify for each Finding)** sends a separate notification for each finding. * **Project** sends a single notification for all findings in a project. * **Dependency** sends a notification for every dependency. * **Dependency per Package Version** sends a notification for every unique combination of dependency and package version. ### Customize email notification templates Endor Labs provides a default template with standard information for the email. You can use the default template or you can choose to edit and customize this template to fit your organization's specific requirements. You can also create custom templates using [Go Templates](https://pkg.go.dev/text/template). 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Manage** on the **Email** card to view the configured notification integrations. 3. Choose a notification integration, click the ellipsis on the right side, and click **Edit Template**. 4. Make required changes to any of the following templates and click **Save Template**. * **Open** - This template applies when Endor Labs raises new notifications. * **Update** - This template applies when an existing notification updates, such as when findings change. * **Resolve** - This template applies when all findings reported by the notification resolve. 5. Click **Restore to Default** to revert the changes. 6. Use the download icon on the top right corner to download this template. 7. Use the copy icon to copy the information in the template. ### Data model To create custom templates for email notifications, you must understand the data supplied to the template. See the `EmailData` message used for **Open** and **Update** templates. See the `ResolvedEmailData` message used for **Resolve** template. See the following protobuf specification for the `NotificationData` message referenced by `EmailData`. To understand Project, Finding, PackageVersion and RepositoryVersion definitions in this protobuf specification, see: * [Project resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#project) * [Finding resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#finding) * [PackageVersion resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#packageversion) * [RepositoryVersion resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#repositoryversion) See the following specification to understand a few additional functions available to the template. You can access these functions by using their corresponding keys. ## Run a scan Run the endorctl scan on your configured projects. See [endorctl scan commands](/developers-api/cli/commands/scan) for more information. You can view email notifications of policy violations in your inbox. # Integrations Source: https://docs.endorlabs.com/integrations/index Learn how to integrate Endor Labs with third-party services. Endor Labs provides multiple out-of-the-box integrations for continuous monitoring, ticketing, and messaging workflows in your environment. Connect source code management platforms for continuous monitoring. Learn how to configure custom package repositories for dependency resolution. Learn how to create webhooks and enable custom integrations with Endor Labs application Learn how to implement ticketing workflows for JIRA. Learn how to integrate Slack with Endor Labs and receive finding notifications Learn how to integrate your email addresses with Endor Labs and receive finding notifications Learn how to integrate Defender for Cloud with Endor Labs to close the gap between Application and Cloud security. Learn how to integrate Vanta with Endor Labs and automate compliance requirements Export scan findings and data to external storage and security platforms. Integrate Endor Labs with third-party security and vulnerability management platforms. # Set up Jira integration with Endor Labs Source: https://docs.endorlabs.com/integrations/jira/index Learn how to implement ticketing workflows for Jira. Integrate Endor Labs with Jira to automatically create tickets in specified projects when scans violate configured policies, aligning with your organization’s existing security workflow. The integration supports both Jira Cloud and Jira Data Center. You can configure the integration with a dedicated service account so credentials are limited to only the required permissions and are not tied to any individual user. This helps maintain consistent access and simplifies credential management. We recommend that the Jira account used for this integration includes only the following minimum required permissions: * Create Issues * Transition Issues * Edit Issues * Resolve Issues * Add Comments To integrate Endor Labs with Jira: * [Generate Jira API token](#generate-jira-api-token) * [Configure Jira Integration on Endor Labs](#configure-jira-integration-on-endor-labs) * [Manage Endor Labs Jira notifications](#manage-endor-labs-jira-notifications) * [Associate an action policy with a Jira notification](#associate-an-action-policy-with-a-jira-notification) * [View ticket details in Jira](#view-ticket-details-in-jira) * [View Jira notification in Endor Labs](#view-jira-notification-in-endor-labs) ## Generate Jira API token Generate Jira API credentials to sign in to Endor Labs. Endor Labs supports both classic and scoped API tokens. Refer to [Create an API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/#Create-an-API-token) to create a classic API token or [Create API token with scopes](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/#Create-an-API-token-with-scopes) to create a scoped API token. For scoped API tokens, select only the `read:jira-work` and `write:jira-work` permissions. You cannot view the token after you close the form. Copy it to a secure location and have it handy. Do not share the token. ## Configure Jira Integration on Endor Labs Set up Jira integration on the Endor Labs application. 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Manage** for Jira. 3. Click **Add Notification Integrations**. 4. Enter a name and description for the integration. 5. Enter a Jira username. The user account appears as the reporter for all the tasks or bugs created in Jira for this notification. We recommend creating a new user account for receiving Jira notifications from Endor Labs. 6. In **API Key**, enter the API token that you generated from Jira. 7. In **Jira URL**, enter the HTTPS endpoint of your Jira instance. 8. Select one of the following In **Authentication Method**: * **Basic Authentication**: If you are using Jira cloud, enter your Jira user name in **Username** and the API token that you generated from Jira in **API Key**. * **Personal Access Token \[PAT]**: If you are using Jira Data Center, enter the personal access token (PAT) in **Access Token**. 9. In **Project Key**, enter the project key of your Jira project in which you want to create the notifications. The project key is the prefix of the bug or task ID. For example, if the project key is `ENG`, Jira creates the task or bug with an ID in the format `ENG-352`. 10. In **Parent ticket issue type**, enter the issue type for the parent ticket, such as `Task`, `Bug`, `Story`, or `Epic`. The issue type is case-sensitive. Make sure to match with an exact issue type on your Jira board. Make sure the endorctl version is `1.6.547` or higher to use **Parent ticket issue type**. 11. In **Child ticket issue type**, enter the issue type for the child tickets that Endor Labs creates under the parent ticket. This applies when you use Dependency or Dependency per package version aggregation. The issue type must follow the [Jira issue type hierarchy](https://support.atlassian.com/jira-cloud-administration/docs/what-are-issue-types/), where the child type is one level below the parent. If you leave this blank, Endor Labs creates child tickets with the project's default sub-task type. Endor Labs supports configuring the child ticket issue type for Jira Cloud only. 12. In **Resolved Status**, specify the resolved status used in your Jira projects. For example, if you enter the value as `Completed`, after you resolve the findings, Endor Labs updates the Jira ticket to this status. If you don't specify a status, Endor Labs attempts to determine your project's resolution status. It defaults to one of the following in priority order: `Done`, `Resolved`, `Closed`, or `Fixed`. If you do not provide a resolved status and your project's resolved status does not match `Done`, `Resolved`, `Closed`, or `Fixed`, you will be unable to configure the integration. 13. In **Labels**, enter a label to associate it with your Jira notifications. 14. For [company-managed Jira project](https://support.atlassian.com/jira-software-cloud/docs/what-are-team-managed-and-company-managed-projects/#Company-managed-projects), enter one or more component values in **Components**. These values are automatically populated in the **Components** field of the created Jira ticket. 15. Click **Add Custom Field** to add custom `key-value` pairs in the created Jira ticket. Use this to create a **Components** field in your team managed Jira project. For example, you can add `Source` as **Key** and associate it to `Endor Labs` in **Value**, so that every notification created will now have the information `Source = Endor Labs` associated with the ticket. For [team-managed Jira project](https://support.atlassian.com/jira-software-cloud/docs/what-are-team-managed-and-company-managed-projects/#Team-managed-projects), use **Add Custom Field** to create a **Components** field in your Jira ticket. In **Key** enter `Components` and enter the component value in **Value**. Ensure that the endorctl version is `1.6.567` or higher to use **Custom Fields**. Check that the **Key** you enter matches an existing custom field in your Jira project. Otherwise, you cannot save the notification and the key-value pair will not appear in your Jira ticket. 16. Click **Propagate this notification target to all child namespaces** to apply this Jira notification target to all child namespaces within the hierarchy. 17. Click **Add Notification Integration**. ### Manage Endor Labs Jira notifications You can view and manage the Endor Labs Jira notifications created for a project. 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Manage** for Jira. 3. To edit a notification, click the vertical three dots and choose **Edit Notification Integration**. 4. To delete a notification, click the vertical three dots and choose **Delete Notification Integration**. ## Associate an action policy with a Jira notification Users can create action policies to execute a recommended action when a scan violates a policy. For example, if there is a license compliance violation, you can create a Jira ticket and notify the required personnel. While creating an action policy, configure the following settings: * Select **Choose an Action** as **Send Notification**. * From **SELECT NOTIFICATION TARGETS**, choose the Jira integration notification that you created. * Choose an **Aggregation type** for Jira notifications. * Choose **None (Notify for each Finding)** to trigger a separate notification for each finding. This can result in a high volume of Jira tickets. * Choose **Project** to trigger a single notification for all findings. * Choose **Dependency** to trigger a notification for every dependency. * Choose **Dependency per package version** to trigger notifications for every unique combination of dependency and package version. See [Aggregation types](/platform-administration/policies/action-policies#aggregation-types-for-notifications) for more details. ### View ticket details in Jira Endor Labs creates a parent ticket named after your project, using the parent issue type you selected. Under it, each dependency gets its own child ticket named after the project and dependency, and findings without a dependency are grouped into a separate child ticket. During future scans, Endor Labs updates these tickets, marks them resolved when their findings are fixed, and creates a new ticket for each new dependency identified. 1. Sign into your Jira account. 2. Navigate to **Projects** drop down menu in the top bar and select your project. 3. Click on the issue to view its details. Jira ticket Endor Labs adds the following labels to a Jira ticket: * `endorlabs-scan`: Indicates that an Endor Labs scan created the ticket. * `endor-severity`: The `endor-severity` label has an associated value, `critical`, `high`, `medium`, or `low`, that reflects the severity of the associated Endor Labs finding. If a ticket includes multiple findings with different severities, the label represents the highest severity among them. For Dependency and Dependency per package version aggregation types, Endor Labs includes the `endor-severity` label in the sub-task. Jira Parent Ticket During future scans, Endor Labs updates the status of the findings as comments on your Jira ticket. * If Endor Labs detects new findings, it adds a comment with their details. New findings Jira comment * If existing findings resolve, Endor Labs adds a comment with their details. Resolved findings Jira comment ### View Jira notification in Endor Labs View created Jira tickets in Endor Labs, including their status (open or closed), associated action policy, and number of violations. 1. Click the bell icon in the top right section of the screen to view **Notifications**. 2. Navigate across **Open**, **Resolved**, **Dismissed**, or **All** to view the issues listed under them. 3. You can view specific details such as created date of the ticket, the name of the policy, the name of the project, the number of violations, and any labels associated with the projects. 4. Choose a notification and click the vertical three dots on the far right side and choose: * **Dismiss Notification**: Stop all further processing and updates for the notification. The notification moves to **Dismissed**. * **Show Details**: View the Jira ticket number and you can also navigate to Jira. * **Go to Policy**: View configuration details of the policy that created this Jira ticket. # Manage security findings in Jira Source: https://docs.endorlabs.com/integrations/jira/jira-with-endor-labs/index Learn how Endor Labs creates and manages Jira tickets for security findings, and choose the right notification aggregation type for your workflow. Explore how to effectively use Endor Labs with Jira to manage security findings within your organization's software development workflows. This integration analyzes your software dependencies, generates security findings, and automatically creates Jira tickets to track and resolve these issues. Each ticket links to your project and contains specific details about the detected vulnerabilities. Ensure you have completed [Jira integration setup](/integrations/jira) before proceeding. ## Track findings in Jira A **finding** is a security vulnerability in your source code. When Endor Labs scans a project, it analyzes its **dependencies**, which are the software packages the project relies on and generates findings. A **package version** is a specific release of a dependency, identified by a version number (for example, `jwx v1.0.5`). Endor Labs automatically creates a Jira ticket to track and address the issue when it identifies a finding. The ticket includes the project URL, branch, details about findings such as: * Finding: A link to the identified vulnerability. * Explanation: A brief description of the issue. * Summary: Technical details about the vulnerability, versions affected, and packages impacted. * Remediation: Recommended actions, such as upgrading to a secure version. * Location: Exact file, package, dependency, and repository where Endor Labs identified the vulnerability. Findings in Jira You can assign the ticket to an individual for remediation. Based on the selected issue type and the aggregation type, it can be one of the following: * Task * Sub-Task * Bug Jira organizes findings and their tickets within a project. A project serves as a centralized space for managing all related issues. To learn more about setting up a project, refer to the [Jira documentation.](https://confluence.atlassian.com/jira061/jira-administrator-s-guide/project-management/defining-a-project) ### Choose the right notification aggregation type Choose the appropriate notification aggregation type to organize security findings in Jira effectively. See [Aggregation Types](/platform-administration/policies/action-policies#aggregation-types-for-notifications) for more information. #### Project Use **Project** aggregation to receive a single Jira notification for all findings in a project. This groups all findings into one Jira ticket. It is ideal for teams that prefer a high-level view of issues. For example, the back-end team relies on libraries such as `archiver` and `jwx`. Endor Labs compiles all findings from these libraries into a single Jira **Task**. This approach helps the teams: * Avoid excessive notifications and streamline remediation efforts. * Manage all security related issues within their designated Jira project. * Improve tracking and collaboration. Project Aggregation Type #### Dependency Use **Dependency** aggregation to receive separate notifications for each affected dependency in a project. Endor Labs creates a parent Jira ticket, with each dependency tracked as a **Sub-Task** with its findings. This approach is ideal for teams prioritizing security management at the dependency level. For example, the back-end team developing a `Go` application relies on libraries like `archiver` and `jwx`. When Endor Labs scans the project: * Findings for `archiver` are present in its **Sub-Task**. * Findings for `jwx` are present in its **Sub-Task**. This approach ensures: * A clear division of responsibilities for efficient vulnerability tracking. * Focused issue resolution without overwhelming teams. * Granular visibility into security risks for targeted management. Dependency Aggregation #### Dependency per package version Use this to receive separate notifications for each affected package version. Each version has its own **Sub-Task** under a parent Jira ticket, with its findings present in the respective **Sub-Task**. For example, a `Go` project using the `jwx` library has multiple versions in use. Endor Labs creates a parent Jira ticket, with each affected version tracked as **Sub-Tasks**: * Findings for `jwx v2.0.13` are present in its **Sub-Task**. * Findings for `jwx v1.0.5` are present in its **Sub-Task**. This approach helps the teams: * Apply security fixes precisely without triggering unnecessary updates. * Reduce notification noise and focus on resolving issues in their specific dependencies. * Maintain stability in machine learning workflows while managing vulnerabilities effectively. Dependency Per Package Version Aggregation #### None (Notify for each Finding) Use this to receive a separate notification for every finding and create an individual Jira ticket for each finding. This aggregation type can produce a high volume of Jira tickets when many findings match the policy. This approach also provides granular tracking so teams can monitor and remediate each issue independently. For example, when you scan the `app-java-demo` project with this aggregation type configured on the action policy, Endor Labs creates a separate Jira **Task** ticket for each finding detected in the project. This approach helps the teams: * Track the remediation status of each vulnerability individually. * Assign findings to different team members for parallel resolution. * Enable clear audit and compliance reporting with one-to-one mapping between findings and tickets. No Aggregation Ensure you have a Jira instance set up on Jira Cloud or Jira Data Center before integrating with Endor Labs. ## Jira tickets Each Jira ticket contains specific labels, comments, and custom fields to provide context and streamline tracking. ### Labels Endor Labs automatically assigns labels to Jira tickets to simplify the management of security issues. These labels appear in the right sidebar of the Jira ticket under **Details**. Endor Labs provides the following labels: `endorlabs-scan`: Assigned to every Jira ticket that an Endor Labs scan generates. `endor-severity`: Indicates the severity of the associated finding, such as `critical`, `high`, `medium`, or `low`. If a ticket includes multiple findings with different severities, the label represents the highest severity among them. For Dependency and Dependency per package version aggregation types, Endor Labs applies the `endor-severity` label to the **Sub-Task** and not the parent ticket. In the following example, the ticket titled "Findings with no dependencies" includes the following labels: `endorlabs-scan`: Identifies the ticket as part of an Endor Labs scan. `endor-severity:medium`: Represents the severity of the detected finding. Example of Jira label ### Comments During future scans, Endor Labs updates the status of the findings in comments on your Jira ticket. When Endor Labs detects new findings, it adds a comment with their details. New findings comment When Endor Labs resolves existing findings, it adds a comment with their details. Update findings comment ### Components Endor Labs automatically sets the **Components** field using values from your Jira project configured during the Jira integration with Endor Labs. * For a [team-managed Jira project](https://support.atlassian.com/jira-software-cloud/docs/what-are-team-managed-and-company-managed-projects/#Team-managed-projects), Endor Labs applies the configured component value to each ticket it creates. In the following example, `Test DEPR Component` is the assigned components value. Team managed project components * For a [company-managed Jira project](https://support.atlassian.com/jira-software-cloud/docs/what-are-team-managed-and-company-managed-projects/#Company-managed-projects), Endor Labs applies all configured component values to each ticket it creates. In the following example, `Test DEPR Component` and `Test UI Component` are the assigned components values. Company managed project components ### Considerations Ensure your Jira board has a designated resolution state like **Done**, **Fixed**, etc. for Endor Labs to mark tickets as resolved. If no such state exists, the ticket remains unresolved. Ensure that tickets can transition from a beginning state, such as **To Do**, to a resolution state like **Done** without requiring intermediate states such as **In Progress**. If the workflow restricts direct movement, Endor Labs cannot move tickets between states, and you must update the status manually on your Jira board. ### FAQs Jira integration requires only the minimum project-level permissions, such as: create issues, transition issues, assign issues, resolve issues, and add comments. If you manually mark a Jira ticket as **Resolved**, Endor Labs skips that finding in future scans and removes it from the ticket. Endor Labs marks the ticket as resolved in your Jira board after the next scan. No. You must add a new Jira integration and then configure Endor Labs to the new project with a new API key. Jira updates the grouping of findings in the board based on changes to the action policy's aggregation type. * Changing from **Project** to **Dependency** splits findings into separate **Sub-tasks** by dependency type. * Changing from **Project** to **Dependency per package version** splits findings into **Sub-tasks** by package version. * Changing from **Dependency** or **Dependency per package version** to **Project** merges all findings into a single Jira ticket. # Set up Microsoft Defender for Cloud integration with Endor Labs Source: https://docs.endorlabs.com/integrations/microsoft-defender-for-cloud/index Learn how to integrate Defender for Cloud with Endor Labs to close the gap between Application and Cloud security. Defender for Cloud, a Cloud-Native Application Protection Platform (CNAPP), provides comprehensive security for hybrid-cloud and multi-cloud environments. It offers advanced threat protection, security posture management, and seamless integration with development workflows. Integrate Defender for Cloud with Endor Labs to mature your security programs. With reachability analysis available directly within the Defender for Cloud console, you can prioritize what to fix based on exploitability without needing to switch tools. And with attack paths showing everywhere vulnerable code is running throughout the SDLC and in the cloud, you have a new way prioritize which vulnerabilities to remediate first. You can correlate SCA findings with runtime alerts to view code-to-runtime attack paths. You can trace vulnerabilities found in open source software (OSS) dependencies directly to potential exploit paths in cloud environments. This allows you to prioritize remediation efforts more effectively and reduce risk across the entire software development lifecycle. Code-to-runtime context also reveals toxic combinations of security issues. For example, there is a reachable vulnerability in an open source package, which runs on an internet-reachable cloud workload. You can see a full attack path, from code committed to Azure DevOps, GitHub, or GitLab, to runtime workloads deployed on Azure, AWS, or Google Cloud Platform. ## Prerequisites Complete the prerequisites in Endor Labs and Defender for Cloud before you can configure the integration. ## Prerequisites in Endor Labs Complete the prerequisites in Endor Labs to prepare your environment to provide findings to Defender for Cloud. * [Create a namespace in which you want to manage the repositories.](/platform-administration/namespaces) You can also use an existing namespace in Endor Labs. * [Deploy Endor Labs in your environment so that your namespace contains the repositories that you want to monitor using Defender for Cloud.](/setup-deployment) * [Create an API key and secret that you can use in the Defender for Cloud integration.](/platform-administration/api-keys) Ensure that the API key has the `Read-Only` permission. We recommend that you set the expiry to 180 days or one year to avoid constant refresh of the key. ## Prerequisites in Defender for Cloud Complete the prerequisites in Defender for Cloud to prepare your repositories for integration and ensure you have sufficient permissions to manage the integration with Endor Labs. * Enable [Defender CSPM](https://learn.microsoft.com/en-us/azure/defender-for-cloud/tutorial-enable-cspm-plan) on the subscription where you wish to see code-to-runtime contextualization. * A user with [Security Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#security-administrator) or [Global Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#global-administrator) permissions on the tenant to create the connector to Endor Labs. * Add repositories that you want to monitor in the tenant. [Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/privileged#contributor) or [Security Admin](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/security#security-admin) permissions on an Azure subscription to create DevOps connectors to Azure DevOps or GitHub. For Azure DevOps, you need Project Collection Administrator permissions to onboard the organization. For GitHub, you need Owner permissions to onboard the organization. * To monitor results, provide a user with at least [Security Reader](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/security#security-reader) or [Reader](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/general#reader) permissions on the subscription with the DevOps connector. * To view the attack paths and code-to-runtime capabilities, the container registry can be in Azure, AWS, GCP, or Docker Hub. The Kubernetes cluster can be in Azure, AWS, or GCP. If you use Azure Kubernetes Cluster (AKS) and Azure Container Registry (ACR) with an [admin account](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-authentication?tabs=azure-cli#admin-account) in the Azure subscription, [attach the ACR to the AKS cluster](https://learn.microsoft.com/en-us/azure/aks/cluster-container-registry-integration?tabs=azure-cli#configure-acr-integration-for-an-existing-aks-cluster) to deploy images from ACR to AKS. ## Configure Defender for Cloud integration You need to configure the integration in Defender for Cloud. 1. In Defender for Cloud, navigate to **Management** > **Environment Settings**. 2. Select **Add Integration** > **Endor Labs**. 3. Enter a name for the integration. 4. Enter the following information from your Endor Labs environment when you configure the integration: * [Endor Labs namespace that you want to integrate](/platform-administration/namespaces) * [Endor Labs API key](/platform-administration/api-keys) * [Endor Labs API secret](/platform-administration/api-keys) 5. Click **Save**. After you configure the integration, Endor Labs data is available in Defender for Cloud. ## Prioritize findings by exploitability From the Defender for Cloud console, you can use Endor Labs' function-reachability analysis to prioritize what to fix based on exploitability. 1. Select **General** > **Cloud Security Explorer**. 2. Select **Query Builder**. 3. Build a query that searches code repositories that have vulnerabilities with reachable functions. Defender for Cloud Query Builder 4. Click **Search** to list results based on the search query. Defender for Cloud Search Results 5. Select a repository to view more details on the vulnerabilities. Defender for Cloud Result Details You can review the findings and also navigate to Endor Labs user interface to view more information on the findings. ## Detect vulnerable code running in the cloud From the Defender for Cloud console, you can view an attack path that visualizes everywhere vulnerable code is running throughout the SDLC and in the cloud. Select **General** > **Attack Path Explorer** to view an attack path of vulnerable code running in a cluster. # Configure integration with AWS Source: https://docs.endorlabs.com/integrations/package-managers/aws-codeartifact/index Learn how to configure package manager integrations with AWS CodeArtifact. Configure Endor Labs to integrate with AWS CodeArtifact to use private libraries to build and scan your software. You must Create an OpenID Connect provider in AWS IAM to allow Endor Labs to authenticate and assume roles securely. Then, configure an IAM role with a trust policy to grant Endor Labs read-only access to AWS CodeArtifact repositories. You can configure the resources using the [AWS Management Console](#create-aws-resources-from-the-aws-user-interface), [AWS CloudFormation Template](#create-the-aws-resources-using-cft-template), or the [AWS CLI](#create-resources-from-the-aws-cli). ## Create AWS resources from the AWS management console Create the AWS resources required for this integration from the AWS user management console. ### Create an OpenID Connect provider In AWS, create an OpenID Connect provider and authenticate Endor Labs to assume roles. 1. Sign into Identity and Access Management (IAM). 2. From **Access Management**, select **Identity Providers**. 3. Click **Add Provider** and choose **OpenID Connect**. 4. In **Provider URL** enter the Endor Labs application URL `https://api.endorlabs.com`. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. 5. Enter an **Audience** such as **endor-aws-code-artifact** and click **Add Provider**. You must keep the **Provider URL** and **Audience** values handy. ### Create an IAM role with trust policies In AWS IAM, create roles that Endor Labs can assume after it authenticates its users or services. Associate each role with a trust policy that grants Endor Labs read-only access to repositories in AWS CodeArtifact. 1. From **IAM**, select **Roles**. 2. Click **Create Role**. 3. From **Trusted entity type**, select **Web Identity** and click **Next**. 4. Select the **Identity provider** you created in the previous task and for **Audience** select the exact value used in the previous task then click **Add condition**. 5. Under **Add condition** set the **Key** to `api.endorlabs.com:sub`, set the **Condition** to `StringLike` and for the **value**, input `/*`. Make sure to replace `` with your tenant name. For example `demo/*`. 6. Add one more condition setting **Key** to `api.endorlabs.com:sub`, set the **Condition** to `StringLike` and for the **value**, input `.*/*`, for example `demo.*/*` and click **Next**. If you're using a EU tenant, use `api.eu.endorlabs.com:sub`. 7. From **Permission policies**, select **AWSCodeArtifactReadOnlyAccess** and click **Next**. 8. Enter a name for the role such as **endor-aws-code-artifact-role** and include an optional description. 9. Review the **Select trusted entities** section, then click **Edit** to make modifications if required. It should look like the following example. ```bash expandable theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:AssumeRoleWithWebIdentity", "Principal": { "Federated": "arn:aws:iam:::oidc-provider/api.endorlabs.com" }, "Condition": { "StringLike": { "api.endorlabs.com:sub": [ "/*", ".*/*" ] }, "StringEquals": { "api.endorlabs.com:aud": [ "endor-aws-code-artifact" ] } } } ] } ``` 10. Click **Create Role**. You must keep the role ARN handy to enter in the Endor Labs application. You can now go and [configure the package manager integration in Endor Labs](#configure-package-manager-integration-in-endor-labs-with-aws-codeartifact) ## Create AWS resources using a CFT template Use AWS CloudFormation Template (CFT) to automate the creation and configuration of AWS resources required for this integration. 1. Create a `.cft` file from the following script entering the OIDC URL, audience, namespace, and role name. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ```bash expandable theme={null} AWSTemplateFormatVersion: '2010-09-09' Description: CloudFormation template to create an IAM OpenID Connect (OIDC) identity provider and an IAM role with AWSCodeArtifactReadOnlyAccess. Parameters: OIDCUrl: Description: The URL of the OIDC provider (e.g., https://api.endorlabs.com). Type: String Default: "https://api.endorlabs.com" ClientId: Description: The audience claim to use in the OIDC trust policy (e.g., endor-aws-code-artifact). Type: String Default: "endor-aws-code-artifact" Namespace: Description: The namespace in the OIDC sub claim to allow (e.g., demo). Type: String Default: "Enter your Endor Labs namespace" RoleName: Description: IAM role name (e.g., endor-aws-code-artifact-role). Type: String Default: "endor-aws-code-artifact-role" Resources: OpenIDConnectProvider: Type: "AWS::IAM::OIDCProvider" Properties: Url: !Ref OIDCUrl ClientIdList: - !Ref ClientId DeletionPolicy: Retain CodeArtifactRole: Type: "AWS::IAM::Role" Properties: RoleName: !Ref RoleName AssumeRolePolicyDocument: Version: "2012-10-17" Statement: - Effect: "Allow" Principal: Federated: !Ref OpenIDConnectProvider # Directly reference OIDC Provider created in the same template Action: "sts:AssumeRoleWithWebIdentity" Condition: StringEquals: "api.endorlabs.com:aud": !Ref ClientId StringLike: "api.endorlabs.com:sub": - !Sub "${Namespace}/*" - !Sub "${Namespace}.*/*" ManagedPolicyArns: - "arn:aws:iam::aws:policy/AWSCodeArtifactReadOnlyAccess" DeletionPolicy: Retain Outputs: TargetRoleArn: Description: The ARN of the newly created IAM role Value: !GetAtt CodeArtifactRole.Arn AllowedAudience: Description: The allowed audience Value: !Ref ClientId ``` 2. Save this file with an appropriate name such as `awscodeartifact-endor-labs.cft`, and have it handy. 3. Sign into AWS CloudFormation and search for **Stacks**. 4. Click **Create Stack** and select **Choose an existing template**. 5. From **Template source**, select **Upload a template file**. 6. Click **Choose file**, select the file you saved `awscodeartifact-endor-labs.cft` and click **Next**. 7. In **Specify stack details**, choose a name for the stack, verify the **Parameters** you entered in the script and click **Next**. 8. Select the acknowledgement from **Configure stack options** and click **Next**. 9. From **Review and Create**, review the details and click **Submit**. Check the progress of the creation of your resources from **Stacks**. After AWS creates the stack, you can see the status as **CREATE\_COMPLETE**. 10. Click **Outputs** to see the target role ARN and the **AllowedAudience** values. Have the values handy to enter in the Endor Labs application. 11. You can now go and [configure the package manager integration in Endor Labs](#configure-package-manager-integration-in-endor-labs-with-aws-codeartifact) ## Create resources from the AWS CLI To create the necessary resources for CodeArtifact integration with the AWS CLI use the following procedure: 1. First, create a new OIDC provider in AWS: If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ```bash theme={null} aws iam create-open-id-connect-provider \ --url https://api.endorlabs.com \ --client-id-list endor-aws-code-artifact ``` 2. Keep the **OpenIDConnectProviderArn** returned during the create command handy. If you lose it you can retrieve it using the following command: ```bash theme={null} aws iam list-open-id-connect-providers ``` 3. Next, you'll need to create a role to provide the OIDC provider access to AWS CodeArtifact. Ensure you replace `` with your Endor Labs namespace and `` with your AWS account ID. ```bash expandable theme={null} aws iam create-role \ --role-name endor-aws-code-artifact-role \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam:::oidc-provider/api.endorlabs.com" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "api.endorlabs.com:aud": "endor-aws-code-artifact" }, "StringLike": { "api.endorlabs.com:sub": [ "/*", ".*/*" ] } } } ] }' ``` 4. Finally, assign the role a permissions policy to access AWS CodeArtifact. ```bash theme={null} aws iam attach-role-policy \ --role-name endor-aws-code-artifact-role \ --policy-arn arn:aws:iam::aws:policy/AWSCodeArtifactReadOnlyAccess ``` 5. You can now go and [configure the package manager integration in Endor Labs](#configure-package-manager-integration-in-endor-labs-with-aws-codeartifact) ## Configure package manager integration in Endor Labs with AWS CodeArtifact After creating an IAM role in AWS with the necessary trust policies, configure AWS CodeArtifact package manager integration within the Endor Labs application. 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select the package manager configuration you'd like to customize and click **Manage** 3. In the upper right-hand corner, select **Add Package Manager**. 4. Select **AWS Code Artifactory**. 5. In **DOMAIN**, enter the name of your repository in AWS CodeArtifact. 6. In **DOMAIN OWNER**, enter the AWS account ID that owns the CodeArtifact repository. 7. In **REPOSITORY**, enter the repository name. 8. In **TARGET ROLE ARN**, enter the role ARN you created. 9. In **ALLOWED AUDIENCE**, enter the **Audience** value specified during role creation. In this example we used **endor-aws-code-artifact**. 10. In **REGION**, enter the AWS region of the AWS Code Artifact Repository. 11. Select if you want to **Propagate this package manager to all child namespaces** from **Advanced**. 12. Click **Add Package Manager**. # Git-based private dependencies Source: https://docs.endorlabs.com/integrations/package-managers/git-based-dependencies/index Beta
Configure Endor Labs to resolve private Git-based dependencies hosted in SCM repositories during scans. Configure Endor Labs to integrate with private Git repositories hosted on GitHub, GitLab, or Bitbucket to access private dependencies during security scanning and analysis. When your projects depend on Git-based dependencies in private repositories, Endor Labs requires authentication credentials to resolve them and generate a complete Software Bill of Materials (SBOM). This integration enables Endor Labs to: * Resolve private Git-based dependencies during dependency resolution. * Generate comprehensive security analysis including private dependencies. * Maintain complete visibility into your software supply chain. You can configure two types of private Git-based dependencies: * **Same-namespace dependencies**: Dependencies on private repositories already covered by an SCM integration in your namespace, such as GitHub, GitLab, or Bitbucket. Endor Labs automatically reuses credentials from every SCM integration in your namespace to resolve them, even when the integration is for a different SCM platform than the project being scanned. Select the private repositories during app installation to improve dependency resolution. You can add repositories to your existing **GitHub Cloud App Pro** installation. See [Manage GitHub Cloud App Pro](/setup-deployment/scm-integrations/github-app/manage-github-app#add-more-github-repositories-to-scan) to learn more. * **Cross-organization dependencies**: Dependencies on private repositories in another project, workspace, or organization where your SCM credentials do not apply. Configure [cross-organization dependencies](#configure-cross-organization-dependencies) and supply credentials to resolve these dependencies. They are supported across GitHub, GitLab, and Bitbucket for the following ecosystems: * Go * npm * Python * Ruby * Rust (Cargo) * Swift Endor Labs resolves private Git-based dependencies that your manifest file or lockfile references over HTTPS, including plain and PAT-embedded URLs, and does not resolve dependencies referenced over SSH. ## Configure cross-organization dependencies Configure this integration to provide additional credentials for repositories not covered by your SCM integrations, such as in a different project, workspace, or organization. Use the Git-based dependencies integration in the following scenarios: * When authentication for private repositories is not defined in standard manifest or configuration files. * When your existing SCM integration does not have access to the repositories on which your project depends. To configure credentials for cross-organization dependencies: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Add** next to **Git-based Dependencies**. 3. Click **Create Git Configuration**. 4. Enter a name for the credential. 5. Select the **Source Code Manager Type** where your private repository is hosted. 6. Enter the organization, group, or repository URL that hosts the private dependencies in **Host URL**. 7. Enter a token with the required permissions for the target repositories in **Access token**. See [Supported SCM platforms and access tokens](#supported-scm-platforms-and-access-tokens) for host URL formats and required permissions for each SCM. Git based dependencies 8. Optionally, click **Advanced** and select **Propagate this configuration to all child namespaces** to apply this configuration to all child namespaces. 9. Click **Create Git Configuration**. You can add multiple credentials for different organizations or repositories on the same or different SCM platforms. ### Supported SCM platforms and access tokens Here are the supported SCM platforms and their corresponding URL formats. Ensure that the access tokens have the following permissions. ### Test Git-based dependency integration You can test the connection for a configured Git-based dependency integration to verify that Endor Labs can reach the repository. To test the connection: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the **Git-based Dependencies** integration. 3. Click the vertical three dots on the integration you want to test and select **Test Connection**. The test checks basic connectivity to the configured host. It does not verify full authentication or authorization with your Git host or across all repositories your scan may require. ### Edit Git-based dependency integration Edit an existing Git-based dependency integration to update the name, host URL, or access token. To edit the integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the **Git-based Dependencies** integration. 3. Click the vertical three dots on the integration you want to edit and select **Edit**. 4. You can modify the name, host URL, or access token as needed. 5. Optionally, click **Advanced** and select **Propagate this configuration to all child namespaces** to apply the dependency configuration to all child namespaces. 6. Click **Save Changes**. ### Delete Git-based dependency integration Delete a Git-based dependency integration when you no longer require that credential or access to that repository. Scans will no longer resolve dependencies from that source. To delete the integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the **Git-based Dependencies** integration. 3. Click the vertical three dots on the integration you want to delete and select **Delete**. 4. Click **Delete this Dependency?** to confirm the deletion when prompted. ## Configure Git-based dependency integration using API Use the Endor Labs API to create, fetch, update, and delete SCM credentials for Git-based dependencies. Provide access tokens for the SCM platforms that host your private dependencies so Endor Labs can authenticate and resolve them during scans. ### Create an SCM credential Run the following command to create an SCM credential resource. Replace: * `` with your namespace. * `` with a unique name for this credential in your namespace. * `PLATFORM_SOURCE_SCM` with the SCM platform constant for your host: `PLATFORM_SOURCE_GITHUB`, `PLATFORM_SOURCE_GITLAB`, or `PLATFORM_SOURCE_BITBUCKET`. * `` with the organization or repository URL that hosts the private dependencies. * `` with a valid access token for the target SCM platform. * `` with a description for the credential. You can optionally set `propagate` to `true` to ensure the credential is available in child namespaces. ```bash theme={null} endorctl api create -r SCMCredential -n -d '{ "meta": { "name": "" }, "spec": { "platform_source": "PLATFORM_SOURCE_SCM", "target_url": "", "access_token": "", "description": "" }, "propagate": false }' ``` ### List SCM credentials using API Run the following command to list all SCM credentials in a namespace. ```bash theme={null} endorctl api list -r SCMCredential -n ``` ### Fetch an SCM credential using API Run the following command to fetch a specific SCM credential using the UUID. ```bash theme={null} endorctl api get -r SCMCredential -n --uuid ``` ### Update an SCM credential Run the following command to update the access token or the host URL. Replace: * `` with your namespace. * `` with the credential's UUID. * `PLATFORM_SOURCE_SCM` with the SCM platform: `PLATFORM_SOURCE_GITHUB`, `PLATFORM_SOURCE_GITLAB`, or `PLATFORM_SOURCE_BITBUCKET`. * `https://platform.org` with the configured organization or repository URL for this credential. * `abcdef12345` with the new access token. Set `--field-mask` to only the fields you are updating, such as `spec.access_token` to update the token or `spec.access_token,spec.target_url` when updating both the access token and host URL. ```bash theme={null} endorctl api update -r SCMCredential -n --uuid \ --field-mask spec.access_token \ -d '{ "spec": { "platform_source": "PLATFORM_SOURCE_SCM", "target_url": "https://platform.org", "access_token": "abcdef12345" } }' ``` ### Delete an SCM credential using API Run the following command to delete an SCM credential using the UUID. Deleting a credential revokes access to the private repositories and can cause dependency resolution errors in subsequent scans. ```bash theme={null} endorctl api delete -r SCMCredential -n --uuid ``` # Configure integration with Google Artifact Registry Source: https://docs.endorlabs.com/integrations/package-managers/google-artifact-registry/index Learn how to configure Endor Labs to authenticate with Google Artifact Registry for agentless dependency scanning. Configure Endor Labs to integrate with Google Artifact Registry (GAR) to resolve private npm, Maven, Gradle, and PyPI packages during agentless scans. GAR uses short-lived OAuth2 access tokens instead of static credentials. Endor Labs creates these tokens automatically at scan time from a service account key that you store securely in the platform. When you configure a GAR integration, Endor Labs stores your encrypted service account key. At scan start, Endor Labs creates a short-lived OAuth2 access token from the stored key, and injects the registry URL and token into the package manager resolver. The token is valid for approximately one hour. ## Supported ecosystems NuGet, Cargo, RubyGems, CocoaPods, and Swift are not supported because Google Artifact Registry does not offer these formats. ## Set up a GCP service account To create a GCP service account with read access to your Artifact Registry repositories: 1. In Google Cloud Console, go to **IAM & Admin** > **Service Accounts**. 2. Select **Create Service Account** and enter a name such as `endor-gar-reader`. 3. Grant the service account the `roles/artifactregistry.reader` role on the target project or repository. 4. Open the service account and select **Keys**. 5. Select **Add Key** > **Create new key**. 6. Choose **JSON** as the key type and select **Create**. 7. Save the downloaded JSON key file and use it when you add the integration. ## Configure a GAR package manager integration To connect Endor Labs to your Artifact Registry repositories: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select **Add** next to the package manager type you want to configure. 3. Select **Add Package Manager**. 4. Enter a **Name** for the integration. 5. Choose **Google Artifact Registry** as the authentication type. 6. Enter your **GCP Project ID**, the ID of the GCP project that hosts the Artifact Registry repository. 7. Enter the **Location**, the GCP region where your repository is hosted, for example `us-central1`. 8. Enter the **Repository**, the name of your GAR repository. 9. Enter the full contents of the downloaded JSON key file in **Service Account Key**. 10. Optionally, under **Advanced**, select **Propagate this package manager to all child namespaces** to share this integration with child namespaces. 11. Optionally, under **Advanced**, select **Use this package manager as a plugin repository** if this registry hosts build plugins rather than library dependencies. 12. Click **Add Package Manager**. Endor Labs tests the connection immediately. If the status indicates a failure, verify that the service account key is valid and that the service account has the roles/artifactregistry.reader role on the target repository. After the integration is saved, the service account key is redacted from all API responses. Store a copy of the JSON key file in a secure location before submitting it. ## Configure a GAR package manager integration using the API Use endorctl to create a GAR package manager resource through the API. The following table lists the parameters required to create the integration. Set `auth_provider.package_manager_type` to match the ecosystem you're configuring, for example `PACKAGE_MANAGER_TYPE_NPM` for npm.
```bash theme={null} endorctl api create -r PackageManager -n -d '{ "meta": { "name": "" }, "spec": { "auth_provider": { "package_manager_type": "PACKAGE_MANAGER_TYPE_NPM", "gar": { "project_id": "", "location": "", "repository": "", "service_account_key": "" } }, "npm": { "priority": 1 } }, "propagate": true }' ```
```bash theme={null} endorctl api create -r PackageManager -n -d '{ "meta": { "name": "" }, "spec": { "auth_provider": { "package_manager_type": "PACKAGE_MANAGER_TYPE_MVN", "gar": { "project_id": "", "location": "", "repository": "", "service_account_key": "" } }, "mvn": { "priority": 1 } }, "propagate": true }' ```
Endor Labs automatically sets the Gradle property key to `ARTIFACT_REGISTRY_AUTH_TOKEN` at scan time. Don't include `property_key_name` or `property_key_value` in the request. Gradle also has no `priority` field. ```bash theme={null} endorctl api create -r PackageManager -n -d '{ "meta": { "name": "" }, "spec": { "auth_provider": { "package_manager_type": "PACKAGE_MANAGER_TYPE_GRADLE", "gar": { "project_id": "", "location": "", "repository": "", "service_account_key": "" } }, "gradle": {} }, "propagate": true }' ```
```bash theme={null} endorctl api create -r PackageManager -n -d '{ "meta": { "name": "" }, "spec": { "auth_provider": { "package_manager_type": "PACKAGE_MANAGER_TYPE_PYPI", "gar": { "project_id": "", "location": "", "repository": "", "service_account_key": "" } }, "pypi": { "priority": 1 } }, "propagate": true }' ```
## Known limitations * **Token lifetime**: GAR access tokens expire approximately one hour after they are minted. A token is minted at the start of the scan and used for package resolution. If package resolution begins more than one hour after the scan starts, authentication fails with a `401 Unauthorized` error. Re-run the scan to generate a new access token and start a fresh one-hour window. * **Long-lived service account key**: The JSON key you provide remains valid until you revoke it in GCP. Rotate the key periodically following your organization's credential management practices and update the integration in Endor Labs after rotation. * **Workload Identity Federation**: Keyless authentication through Workload Identity Federation is not supported in this release. # Private package manager integration for Gradle Source: https://docs.endorlabs.com/integrations/package-managers/gradle-private-package-manager/index Learn how to configure Endor Labs to access private Gradle repositories for dependency resolution and security scanning. Configure Endor Labs to integrate with private Gradle repositories to access proprietary dependencies during security scanning and analysis. When your Gradle projects depend on artifacts hosted in private or corporate repositories, Endor Labs requires authentication credentials to resolve these dependencies and generate a complete bill of materials. This integration enables Endor Labs to: * Access private Gradle artifacts during dependency resolution * Generate comprehensive security analysis including private dependencies * Maintain complete visibility into your software supply chain Endor Labs generally respects package authentication and configuration settings and a package manager integration is usually not required to scan private packages successfully. * Use package manager integrations to simplify scanning when authentication to private repositories is not part of standard manifest or settings files. * Package manager integrations allow you to set custom repositories for each package ecosystem and the priority of each repository for scanning. To set up a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select **Add** next to the package manager configuration you want to add. 3. Select **Add Package Manager**. 4. Enter a **Name** for the integration. 5. Choose an authentication type and complete the required fields.
Enter your registry URL and static credentials.

AWS CodeArtifact authentication uses OIDC token federation. No static credentials are stored. Enter the following fields:

  • Domain: Name of your AWS CodeArtifact domain.
  • Domain Owner: AWS account ID that owns the domain.
  • Repository: Name of the CodeArtifact repository.
  • Target Role ARN: ARN of the IAM role Endor Labs assumes.
  • Allowed Audience: Audience value specified when you created the OIDC provider.
  • Region: AWS region of the repository.

See Configure integration with AWS CodeArtifact for setup instructions.
  1. Optionally, under Advanced, select Propagate this package manager to all child namespaces to share this integration with child namespaces.
  2. Click Add Package Manager.
### Test package manager integration For Gradle, connection testing applies only to AWS CodeArtifact and Google Artifact Registry integrations. A Basic integration has no endpoint to test. It shows **Last Tested: N/A** and you can validate it by running a scan or a manual curl against your private registry. You can test the connection to a configured package manager to verify that Endor Labs can reach the repository. To test the connection: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** in the package manager configuration you want to customize. 3. Click the vertical three dots of the package manager configured and select **Test Connection**. The integration does not perform authentication or authorization checks on the package manager repository. ### Edit package manager integration You can edit an existing package manager integration to update the name, repository URL, or authentication credentials. To edit a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the package manager you want to edit. 3. Click the vertical three dots on the configured integration you want to edit and select **Edit**. 4. You can modify the name, package manager URL, and credentials. 5. Click **Save Changes**. ## Private package manager integration for Gradle using API Configure private package manager integration with Gradle to authenticate and fetch dependencies from private repositories during scans. Gradle requires valid credentials, such as AWS access keys and GitHub or GitLab tokens, to access private repositories and fetch dependencies. Provide these credentials through the endorctl API call for GitHub App scans to run successfully. The variable names you define (like `mavenAccessKey`, `mavenSecretKey`) must exactly match the property names referenced in `settings.gradle`, `build.gradle`, or `gradle.properties` files when configuring credentials. For more information on how to align variable names with your build configuration, refer to [Declaring private repositories.](https://docs.gradle.org/current/userguide/declaring_repositories.html#sub:declaring-custom-repository-basics) You can configure these credentials for the scans performed through the GitHub App. ### Set Gradle credentials Use endorctl to configure your repository credentials. You can set the necessary Gradle properties, allowing access to private repositories during the Gradle build process. For example, to authenticate with an AWS S3-backed Maven repository, run the following commands to set the `mavenAccessKey` and `mavenSecretKey` properties. Replace `namespace` with your namespace. ```shell theme={null} endorctl api create -n -r PackageManager -d '{ "meta": { "name": "gradle properties" }, "spec": { "gradle": { "property_key_name": "mavenAccessKey", "property_key_value": "your-access-key" } } }' ``` ```shell theme={null} endorctl api create -n -r PackageManager -d '{ "meta": { "name": "gradle properties" }, "spec": { "gradle": { "property_key_name": "mavenSecretKey", "property_key_value": "your-secret-key" } } }' ``` These credentials will then be available to your Gradle build at scan time. All values configured through the API are automatically exported as environment variables. ### Considerations When configuring Gradle credentials, consider the following scenarios: #### AWS credentials with scan profile If you link a scan profile to your project, AWS credentials are directly written into `~/.gradle/gradle.properties` and require exact key matches. You can use one of the following combinations: * `AWS_ACCESS_KEY` and `AWS_SECRET_KEY` * `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` #### Resolve Gradle plugins from a private Maven registry If your Gradle build fails to resolve plugins hosted in a private Maven-format registry, configure a Gradle package manager integration. Use the same Gradle integration you already use for private library dependency resolution. A Gradle package manager integration always applies to plugin resolution as well as library dependency resolution. Set the **Property Key** and **Property Value** fields to match your `settings.gradle` `pluginManagement` block declares for authentication. Gradle supports two credential types: * **PasswordCredentials**: A username property and a password property. * **HttpHeaderCredentials**: A header-based credential, commonly a bearer token sent in the `Authorization` header. endorctl exports each configured property as an `ORG_GRADLE_PROJECT_` environment variable. The `` value is case sensitive. It must match the property name your `pluginManagement` block's `credentials` or `url` declarations reference, such as `artifactory_contextUrl` or `artifactory_password`. For more information, refer to [Declaring private repositories.](https://docs.gradle.org/current/userguide/declaring_repositories.html#sub:declaring-custom-repository-basics) #### Authenticate using mutual TLS Use mutual TLS to securely authenticate to artifact repositories. Currently, you can configure mutual TLS only through the API. See [mTLS authentication](/integrations/package-managers/mtls-authentication) for more information. ### Fetch package manager using API Run the following command to fetch the package manager using the UUID. ```bash theme={null} endorctl api get -r packageManager -n --uuid ``` ### Delete package manager using API Run the following command to delete the package manager using the UUID. ```bash theme={null} endorctl api delete -r packageManager -n --uuid ``` # Set up custom package repositories Source: https://docs.endorlabs.com/integrations/package-managers/index Learn how to configure custom package repositories for dependency resolution. Suppose your software components are private and reside in an internal package repository. In that case, you must provide authentication credentials to the registry, to create a complete bill of materials or perform static analysis. Authenticate to private Maven, npm, PyPI, Gradle, NuGet, Swift, Ruby, and PHP registries using static credentials or mTLS. Use OIDC token federation to authenticate to AWS CodeArtifact without storing static credentials. Authenticate using short-lived OAuth2 tokens minted from a GCP service account key. Resolve private Git-based dependencies hosted on GitHub, GitLab, or Bitbucket during scans. Authenticate to private package repositories using mutual TLS certificates. You must set up custom package repositories if: * Authentication credentials for your private registry are not stored in project manifest or settings files, such as `.npmrc`, `settings.xml`, or `pip.conf`. * You are using the Endor Labs GitHub App or agentless scanning, where local package manager configuration is not available at scan time. * You want to specify a custom repository URL for a package ecosystem instead of using the default public registry. * You want to control the priority order of repositories used during dependency resolution. If your software components are private and hosted in AWS CodeArtifact, set up an OpenID Connect provider in AWS. Create roles with trust policies to allow Endor Labs access to your CodeArtifact repositories. See [Configure package manager integrations with AWS](/integrations/package-managers/aws-codeartifact). You can authenticate to private package artifact repositories using mutual TLS. See [mTLS authentication](/integrations/package-managers/mtls-authentication) to learn how to set up and authenticate. ## Package manager integration support matrix The following support matrix details support for package manager integrations: Private package manager integrations for Golang and Rust are not supported. ## Change package manager integration priority Package manager integrations allow you to set the priority of each package repository used by a package manager in your tenant namespace. This defines the location from which a package manager looks when it attempts to resolve dependencies for a software package. To change the package manager integration priority: 1. Click and hold the integration you would like to change the priority of. 2. Drag the integration to the priority spot that is most frequently used by your organization. # Private package manager integration for Maven Source: https://docs.endorlabs.com/integrations/package-managers/maven-private-package-manager/index Learn how to configure Endor Labs to access private Maven repositories for dependency resolution and security scanning. Configure Endor Labs to integrate with private Maven repositories to access proprietary dependencies during security scanning and analysis. When your Maven projects depend on artifacts hosted in private or corporate repositories, Endor Labs requires authentication credentials to resolve these dependencies and generate a complete bill of materials. This integration enables Endor Labs to: * Access private Maven artifacts during dependency resolution * Generate comprehensive security analysis including private dependencies * Maintain complete visibility into your software supply chain Endor Labs generally respects package authentication and configuration settings and a package manager integration is usually not required to scan private packages successfully. * Use package manager integrations to simplify scanning when authentication to private repositories is not part of standard manifest or settings files. * Package manager integrations allow you to set custom repositories for each package ecosystem and the priority of each repository for scanning. To set up a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select **Add** next to the package manager configuration you want to add. 3. Select **Add Package Manager**. 4. Enter a **Name** for the integration. 5. Choose an authentication type and complete the required fields.
Enter your registry URL and static credentials.

AWS CodeArtifact authentication uses OIDC token federation. No static credentials are stored. Enter the following fields:

  • Domain: Name of your AWS CodeArtifact domain.
  • Domain Owner: AWS account ID that owns the domain.
  • Repository: Name of the CodeArtifact repository.
  • Target Role ARN: ARN of the IAM role Endor Labs assumes.
  • Allowed Audience: Audience value specified when you created the OIDC provider.
  • Region: AWS region of the repository.

See Configure integration with AWS CodeArtifact for setup instructions.
  1. Optionally, under Advanced, select Propagate this package manager to all child namespaces to share this integration with child namespaces.
  2. Click Add Package Manager.
### Test package manager integration You can test the connection to a configured package manager to verify that Endor Labs can reach the repository. To test the connection: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** in the package manager configuration you want to customize. 3. Click the vertical three dots of the package manager configured and select **Test Connection**. The integration does not perform authentication or authorization checks on the package manager repository. ### Edit package manager integration You can edit an existing package manager integration to update the name, repository URL, or authentication credentials. To edit a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the package manager you want to edit. 3. Click the vertical three dots on the configured integration you want to edit and select **Edit**. 4. You can modify the name, package manager URL, and credentials. 5. Click **Save Changes**. ## Private package manager integration for Maven using API Use endorctl to create a package manager resource through an API call and configure authentication for accessing private repositories during scans. Maven package manager configurations apply only to Maven build projects and not to Gradle build projects that use Maven repositories. Run the following command to create a package manager resource and authenticate to a private repository. Replace: * `username` with your package registry username * `xxxx` with your package registry password * `namespace` with your namespace. ```shell expandable theme={null} endorctl api create -r PackageManager -n -d ' { "meta": { "name": "test", "description": "test" }, "spec": { "maven": { "priority": 1, "url": "package manager url", "user": "username", "password": "xxxx" } }, "propagate": true }' ``` **Configure as a plugin repository** To configure a Maven integration as a plugin repository, add `"is_plugin_repository": true` in the spec. ### Fetch package manager using API Run the following command to fetch the package manager using the UUID. ```bash theme={null} endorctl api get -r packageManager -n --uuid ``` ### Delete package manager using API Run the following command to delete the package manager using the UUID. ```bash theme={null} endorctl api delete -r packageManager -n --uuid ``` # Authenticate to private packages using mTLS Source: https://docs.endorlabs.com/integrations/package-managers/mtls-authentication/index Learn how to configure custom package repositories for dependency resolution using mTLS. Mutual Transport Layer Security (mTLS) is a protocol that mandates both the sender and receiver to authenticate each other before establishing a secure connection. Each party verifies the other's certificate, ensuring authenticity and trust. This establishes a secure connection between both the parties. Use mutual TLS to securely authenticate to artifact repositories. ## Set up mTLS Perform the following steps to set up a secure mTLS connection: If your certificate is in PKCS12 format, you can start with step 1. If you already have a PEM certificate, you can skip to step 2. 1. Generate client certificate and client key Run the following command to generate the client certificate in the Privacy Enhanced Mail (PEM) format. Replace `` with the name of your `.p12` file. ```shell theme={null} openssl pkcs12 -in .p12 -clcerts -nokeys | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > client.crt ``` Run the following command to generate the client key in the Privacy Enhanced Mail (PEM) format. Replace `` with the name of your `.p12` file. ```shell theme={null} openssl pkcs12 -in .p12 -nocerts -nodes | sed -ne '/-BEGIN PRIVATE KEY-/,/-END PRIVATE KEY-/p' > client.key ``` Ensure you have your PKCS12 certificate and its password ready. When prompted, enter the password. 2. Format the client certificate and client key as json Run the following command to format the client certificate as json: ```shell theme={null} awk '{printf "%s\\n", $0}' client.crt ``` Run the following command to format the client key as json: ```shell theme={null} awk '{printf "%s\\n", $0}' client.key ``` 3. Create a package manager resource after generating the client certificate and client key. ### Authenticate to Gradle repository Run the following command to create a package manager resource and authenticate to Gradle artifact repository. Replace `namespace` with your namespace. ```shell expandable theme={null} endorctl api create -n -r packageManager -d '{ "meta": { "name": "test mtls for npm creation", "description": "test mtls creation" }, "spec": { "gradle": { "property_key_name": "ENDOR_MTLS_CONFIGURATION", "property_key_value": "any non empty value", "mtls": { "client_cert": "formatted pem client.crt", "client_key": "formatted pem client.key" } } } }' ``` The `property_key_name` must match exactly **ENDOR\_MTLS\_CONFIGURATION**. ### Authenticate to Maven repository Run the following command to create a package manager resource and authenticate to Maven repository. Replace: * `namespace` with your namespace. * `https://nexus.example.com/repository/public` with your Maven repository URL. ```shell expandable theme={null} endorctl api create -n -r packageManager -d '{ "meta": { "name": "test mtls for npm creation", "description": "test mtls creation" }, "spec": { "mvn": { "url": "https://nexus.example.com/repository/public", "mtls": { "client_cert": "formatted pem client.crt", "client_key": "formatted pem client.key" } } } }' ``` ### Authenticate to PyPI repository Run the following command to create a package manager resource and authenticate to PyPI repository. Replace: * `namespace` with your namespace. * `https://nexus.example.com/repository/pypi` with your PyPI repository URL. ```shell expandable theme={null} endorctl api create -n -r packageManager -d '{ "meta": { "name": "test mtls for python creation", "description": "test mtls creation" }, "spec": { "pypi": { "priority": 1, "url": "https://nexus.example.com/repository/pypi", "mtls": { "client_cert": "formatted pem client.crt", "client_key": "formatted pem client.key" } } } }' ``` ### Authenticate to npm registry Run the following command to create a package manager resource and authenticate to npm registry. Replace: * `namespace` with your namespace. * `https://nexus.example.com/repository/npm` with your npm registry URL. ```shell expandable theme={null} endorctl api create -n -r packageManager -d '{ "meta": { "name": "test mtls for npm creation", "description": "test mtls creation" }, "spec": { "npm": { "url": "https://nexus.example.com/repository/npm", "mtls": { "client_cert": "formatted pem client.crt", "client_key": "formatted pem client.key" } } } }' ``` # Private package manager integration for npm Source: https://docs.endorlabs.com/integrations/package-managers/npm-private-package-manager/index Learn how to configure Endor Labs to access private npm repositories for dependency resolution and security scanning. Configure Endor Labs to integrate with private npm repositories to access proprietary dependencies during security scanning and analysis. When your JavaScript or Node.js projects depend on packages in private or corporate repositories, Endor Labs needs authentication credentials. These credentials let Endor Labs resolve dependencies and generate a complete bill of materials. This integration enables Endor Labs to: * Access private npm packages during dependency resolution * Generate comprehensive security analysis including private dependencies * Maintain complete visibility into your software supply chain Endor Labs generally respects package authentication and configuration settings and a package manager integration is usually not required to scan private packages successfully. * Use package manager integrations to simplify scanning when authentication to private repositories is not part of standard manifest or settings files. * Package manager integrations allow you to set custom repositories for each package ecosystem and the priority of each repository for scanning. To set up a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select **Add** next to the package manager configuration you want to add. 3. Select **Add Package Manager**. 4. Enter a **Name** for the integration. 5. Choose an authentication type and complete the required fields.
Enter your registry URL and static credentials.

AWS CodeArtifact authentication uses OIDC token federation. No static credentials are stored. Enter the following fields:

  • Domain: Name of your AWS CodeArtifact domain.
  • Domain Owner: AWS account ID that owns the domain.
  • Repository: Name of the CodeArtifact repository.
  • Target Role ARN: ARN of the IAM role Endor Labs assumes.
  • Allowed Audience: Audience value specified when you created the OIDC provider.
  • Region: AWS region of the repository.

See Configure integration with AWS CodeArtifact for setup instructions.
  1. Optionally, under Advanced, select Propagate this package manager to all child namespaces to share this integration with child namespaces.
  2. Click Add Package Manager.
### Test package manager integration You can test the connection to a configured package manager to verify that Endor Labs can reach the repository. To test the connection: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** in the package manager configuration you want to customize. 3. Click the vertical three dots of the package manager configured and select **Test Connection**. The integration does not perform authentication or authorization checks on the package manager repository. ### Edit package manager integration You can edit an existing package manager integration to update the name, repository URL, or authentication credentials. To edit a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the package manager you want to edit. 3. Click the vertical three dots on the configured integration you want to edit and select **Edit**. 4. You can modify the name, package manager URL, and credentials. 5. Click **Save Changes**. ## Package manager integration for npm using API Use endorctl to create a package manager resource for your private npm registry and authenticate using one of the following tokens: * Base64-encoded username and password * Basic authentication token You can configure multiple npm package managers only if each configuration has its own scope. ### Base64-encoded authentication token 1. Generate base64 token To generate the base64 encoded username and password, run the following command. Copy the token generated and store it in a secure place. ```shell theme={null} echo -n 'username:plain_password' | openssl base64 ``` 2. Create package manager resource Run the following command to create a package manager resource and authenticate to npm registry using base64 token without scope. Replace: * `base64 token` with the generated base64 encoded username and password in the previous step. * `namespace` with your namespace. ```shell theme={null} endorctl api create -r PackageManager -n -d ' { "meta": { "name": "test npm with base64", "description": "test npm with base 64 token without scope" }, "spec": { "npm": { "priority": 1, "url": "package manager url" "token": "base64 token" } }, "propagate": true } ' ``` ### Basic authentication token Run the following command to create a package manager resource and authenticate to npm registry using basic authentication token with scope. Replace: * `xxx` with your authentication token. * `namespace` with your namespace. * `scope` with your scope. For example, `"scope":"abc-corp"`. ```shell expandable theme={null} endorctl api create -r PackageManager -n -d ' { "meta": { "name": "test npm with auth token", "description": "test npm with auth token with scope" }, "spec": { "npm": { "priority": 1, "scope": "scope", "url": "package manager url", "auth_token": "xxxx" } }, "propagate": true } ' ``` ### Fetch package manager using API Run the following command to fetch the package manager using the UUID. ```bash theme={null} endorctl api get -r packageManager -n --uuid ``` ### Delete package manager using API Run the following command to delete the package manager using the UUID. ```bash theme={null} endorctl api delete -r packageManager -n --uuid ``` # Private package manager integration for NuGet Source: https://docs.endorlabs.com/integrations/package-managers/nuget-private-package-manager/index Learn how to configure Endor Labs to access private NuGet repositories for dependency resolution and security scanning. Configure Endor Labs to integrate with private NuGet repositories to access proprietary dependencies during security scanning and analysis. When your .NET projects depend on packages hosted in private or corporate repositories, Endor Labs requires authentication credentials to resolve these dependencies and generate a complete bill of materials. This integration enables Endor Labs to: * Access private NuGet packages during dependency resolution * Generate comprehensive security analysis including private dependencies * Maintain complete visibility into your software supply chain Endor Labs generally respects package authentication and configuration settings and a package manager integration is usually not required to scan private packages successfully. * Use package manager integrations to simplify scanning when authentication to private repositories is not part of standard manifest or settings files. * Package manager integrations allow you to set custom repositories for each package ecosystem and the priority of each repository for scanning. To set up a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select **Add** next to the package manager configuration you want to add. 3. Select **Add Package Manager**. 4. Enter a **Name** for the integration. 5. Choose an authentication type and complete the required fields.
Enter your registry URL and static credentials.

AWS CodeArtifact authentication uses OIDC token federation. No static credentials are stored. Enter the following fields:

  • Domain: Name of your AWS CodeArtifact domain.
  • Domain Owner: AWS account ID that owns the domain.
  • Repository: Name of the CodeArtifact repository.
  • Target Role ARN: ARN of the IAM role Endor Labs assumes.
  • Allowed Audience: Audience value specified when you created the OIDC provider.
  • Region: AWS region of the repository.

See Configure integration with AWS CodeArtifact for setup instructions.
  1. Optionally, under Advanced, select Propagate this package manager to all child namespaces to share this integration with child namespaces.
  2. Click Add Package Manager.
### Test package manager integration You can test the connection to a configured package manager to verify that Endor Labs can reach the repository. To test the connection: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** in the package manager configuration you want to customize. 3. Click the vertical three dots of the package manager configured and select **Test Connection**. The integration does not perform authentication or authorization checks on the package manager repository. ### Edit package manager integration You can edit an existing package manager integration to update the name, repository URL, or authentication credentials. To edit a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the package manager you want to edit. 3. Click the vertical three dots on the configured integration you want to edit and select **Edit**. 4. You can modify the name, package manager URL, and credentials. 5. Click **Save Changes**. ## Private package manager integration for NuGet using API Use endorctl to create a package manager resource through an API call and configure authentication for accessing private repositories during scans. Run the following command to create a package manager resource and authenticate to private repository. Replace: * `username` with your package registry username * `xxxx` with your package registry password * `namespace` with your namespace. ```shell expandable theme={null} endorctl api create -r PackageManager -n -d ' { "meta": { "name": "test", "description": "test" }, "spec": { "nuget": { "priority": 1, "url": "package manager url", "user": "username", "password": "xxxx" } }, "propagate": true } ' ``` ### Fetch package manager using API Run the following command to fetch the package manager using the UUID. ```bash theme={null} endorctl api get -r packageManager -n --uuid ``` ### Delete package manager using API Run the following command to delete the package manager using the UUID. ```bash theme={null} endorctl api delete -r packageManager -n --uuid ``` # Private package manager integration for Packagist Source: https://docs.endorlabs.com/integrations/package-managers/packagist-private-package-manager/index Learn how to configure Endor Labs to access private Packagist repositories for dependency resolution and security scanning. Configure Endor Labs to integrate with private Packagist repositories to access proprietary dependencies during security scanning and analysis. When your PHP projects depend on packages hosted in private or corporate Packagist repositories, Endor Labs requires authentication credentials to resolve these dependencies and generate a complete bill of materials. This integration enables Endor Labs to: * Access private Packagist packages during dependency resolution * Generate comprehensive security analysis including private dependencies * Maintain complete visibility into your software supply chain Endor Labs generally respects package authentication and configuration settings and a package manager integration is usually not required to scan private packages successfully. * Use package manager integrations to simplify scanning when authentication to private repositories is not part of standard manifest or settings files. * Package manager integrations allow you to set custom repositories for each package ecosystem and the priority of each repository for scanning. To set up a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select **Add** next to the package manager configuration you want to add. 3. Select **Add Package Manager**. 4. Enter a **Name** for the integration. 5. Choose an authentication type and complete the required fields.
Enter your registry URL and static credentials.

AWS CodeArtifact authentication uses OIDC token federation. No static credentials are stored. Enter the following fields:

  • Domain: Name of your AWS CodeArtifact domain.
  • Domain Owner: AWS account ID that owns the domain.
  • Repository: Name of the CodeArtifact repository.
  • Target Role ARN: ARN of the IAM role Endor Labs assumes.
  • Allowed Audience: Audience value specified when you created the OIDC provider.
  • Region: AWS region of the repository.

See Configure integration with AWS CodeArtifact for setup instructions.
  1. Optionally, under Advanced, select Propagate this package manager to all child namespaces to share this integration with child namespaces.
  2. Click Add Package Manager.
### Test package manager integration You can test the connection to a configured package manager to verify that Endor Labs can reach the repository. To test the connection: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** in the package manager configuration you want to customize. 3. Click the vertical three dots of the package manager configured and select **Test Connection**. The integration does not perform authentication or authorization checks on the package manager repository. ### Edit package manager integration You can edit an existing package manager integration to update the name, repository URL, or authentication credentials. To edit a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the package manager you want to edit. 3. Click the vertical three dots on the configured integration you want to edit and select **Edit**. 4. You can modify the name, package manager URL, and credentials. 5. Click **Save Changes**. ## Package manager integration for Packagist using API Run the following command to create a package manager resource and authenticate to Packagist repository. Replace: * `username` with your package registry username. * `xxxx` with your package registry password. * `namespace` with your namespace. * `your host` with your package manager host. For example, `"host": "repo.packagist.com"`. ```shell expandable theme={null} endorctl api create -r PackageManager -n -d ' { "meta": { "name": "test packagist", "description": "test packagist" }, "spec": { "packagist": { "auth_kind": "AUTH_KIND_HTTP_BASIC", "host": "your host", "user": "username", "password": "xxxx" } }, "propagate": true } ' ``` ### Fetch package manager using API Run the following command to fetch the package manager using the UUID. ```bash theme={null} endorctl api get -r packageManager -n --uuid ``` ### Delete package manager using API Run the following command to delete the package manager using the UUID. ```bash theme={null} endorctl api delete -r packageManager -n --uuid ``` # Private package manager integration for PyPI Source: https://docs.endorlabs.com/integrations/package-managers/pypi-private-package-manager/index Learn how to configure Endor Labs to access private PyPI repositories for dependency resolution and security scanning. Configure Endor Labs to integrate with private PyPI repositories to access proprietary dependencies during security scanning and analysis. When your Python projects depend on packages hosted in private or corporate repositories, Endor Labs requires authentication credentials to resolve these dependencies and generate a complete bill of materials. This integration enables Endor Labs to: * Access private PyPI packages during dependency resolution * Generate comprehensive security analysis including private dependencies * Maintain complete visibility into your software supply chain Endor Labs generally respects package authentication and configuration settings and a package manager integration is usually not required to scan private packages successfully. * Use package manager integrations to simplify scanning when authentication to private repositories is not part of standard manifest or settings files. * Package manager integrations allow you to set custom repositories for each package ecosystem and the priority of each repository for scanning. To set up a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select **Add** next to the package manager configuration you want to add. 3. Select **Add Package Manager**. 4. Enter a **Name** for the integration. 5. Choose an authentication type and complete the required fields.
Enter your registry URL and static credentials.

AWS CodeArtifact authentication uses OIDC token federation. No static credentials are stored. Enter the following fields:

  • Domain: Name of your AWS CodeArtifact domain.
  • Domain Owner: AWS account ID that owns the domain.
  • Repository: Name of the CodeArtifact repository.
  • Target Role ARN: ARN of the IAM role Endor Labs assumes.
  • Allowed Audience: Audience value specified when you created the OIDC provider.
  • Region: AWS region of the repository.

See Configure integration with AWS CodeArtifact for setup instructions.
  1. Optionally, under Advanced, select Propagate this package manager to all child namespaces to share this integration with child namespaces.
  2. Click Add Package Manager.
### Test package manager integration You can test the connection to a configured package manager to verify that Endor Labs can reach the repository. To test the connection: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** in the package manager configuration you want to customize. 3. Click the vertical three dots of the package manager configured and select **Test Connection**. The integration does not perform authentication or authorization checks on the package manager repository. ### Edit package manager integration You can edit an existing package manager integration to update the name, repository URL, or authentication credentials. To edit a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the package manager you want to edit. 3. Click the vertical three dots on the configured integration you want to edit and select **Edit**. 4. You can modify the name, package manager URL, and credentials. 5. Click **Save Changes**. ## Private package manager integration for PyPI using API Use endorctl to create a package manager resource through an API call and configure authentication for accessing private repositories during scans. The PyPI package manager URL typically ends with `/simple`. Run the following command to create a package manager resource and authenticate to private repository. Replace: * `username` with your package registry username * `xxxx` with your package registry password * `namespace` with your namespace. ```shell expandable theme={null} endorctl api create -r PackageManager -n -d ' { "meta": { "name": "test", "description": "test" }, "spec": { "pypi": { "priority": 1, "url": "package manager url", "user": "username", "password": "xxxx" } }, "propagate": true } ' ``` ### Fetch package manager using API Run the following command to fetch the package manager using the UUID. ```bash theme={null} endorctl api get -r packageManager -n --uuid ``` ### Delete package manager using API Run the following command to delete the package manager using the UUID. ```bash theme={null} endorctl api delete -r packageManager -n --uuid ``` # Private package manager integration for RubyGems Source: https://docs.endorlabs.com/integrations/package-managers/rubygems-private-package-manager/index Learn how to configure Endor Labs to access private RubyGems repositories for dependency resolution and security scanning. Configure Endor Labs to integrate with private RubyGems repositories to access proprietary dependencies during security scanning and analysis. When your Ruby projects depend on gems hosted in private or corporate repositories, Endor Labs requires authentication credentials to resolve these dependencies and generate a complete bill of materials. This integration enables Endor Labs to: * Access private RubyGems during dependency resolution * Generate comprehensive security analysis including private dependencies * Maintain complete visibility into your software supply chain Endor Labs generally respects package authentication and configuration settings and a package manager integration is usually not required to scan private packages successfully. * Use package manager integrations to simplify scanning when authentication to private repositories is not part of standard manifest or settings files. * Package manager integrations allow you to set custom repositories for each package ecosystem and the priority of each repository for scanning. To set up a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select **Add** next to the package manager configuration you want to add. 3. Select **Add Package Manager**. 4. Enter a **Name** for the integration. 5. Choose an authentication type and complete the required fields.
Enter your registry URL and static credentials.

AWS CodeArtifact authentication uses OIDC token federation. No static credentials are stored. Enter the following fields:

  • Domain: Name of your AWS CodeArtifact domain.
  • Domain Owner: AWS account ID that owns the domain.
  • Repository: Name of the CodeArtifact repository.
  • Target Role ARN: ARN of the IAM role Endor Labs assumes.
  • Allowed Audience: Audience value specified when you created the OIDC provider.
  • Region: AWS region of the repository.

See Configure integration with AWS CodeArtifact for setup instructions.
  1. Optionally, under Advanced, select Propagate this package manager to all child namespaces to share this integration with child namespaces.
  2. Click Add Package Manager.
### Test package manager integration You can test the connection to a configured package manager to verify that Endor Labs can reach the repository. To test the connection: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** in the package manager configuration you want to customize. 3. Click the vertical three dots of the package manager configured and select **Test Connection**. The integration does not perform authentication or authorization checks on the package manager repository. ### Edit package manager integration You can edit an existing package manager integration to update the name, repository URL, or authentication credentials. To edit a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the package manager you want to edit. 3. Click the vertical three dots on the configured integration you want to edit and select **Edit**. 4. You can modify the name, package manager URL, and credentials. 5. Click **Save Changes**. ## Private package manager integration for RubyGems using API Use endorctl to create a package manager resource through an API call and configure authentication for accessing private repositories during scans. Run the following command to create a package manager resource and authenticate to private repository. Replace: * `username` with your package registry username * `xxxx` with your package registry password * `namespace` with your namespace. ```shell expandable theme={null} endorctl api create -r PackageManager -n -d ' { "meta": { "name": "test", "description": "test" }, "spec": { "gem": { "priority": 1, "url": "package manager url", "user": "username", "password": "xxxx" } }, "propagate": true } ' ``` ### Fetch package manager using API Run the following command to fetch the package manager using the UUID. ```bash theme={null} endorctl api get -r packageManager -n --uuid ``` ### Delete package manager using API Run the following command to delete the package manager using the UUID. ```bash theme={null} endorctl api delete -r packageManager -n --uuid ``` # Private package manager integration for Swift Source: https://docs.endorlabs.com/integrations/package-managers/swift-private-package-manager/index Learn how to configure Endor Labs to access private Swift package repositories for dependency resolution and security scanning. Configure Endor Labs to integrate with private Swift package repositories to access proprietary dependencies during security scanning and analysis. When your Swift projects depend on packages hosted in private or corporate repositories, Endor Labs requires authentication credentials to resolve these dependencies and generate a complete bill of materials. This integration enables Endor Labs to: * Access private Swift packages during dependency resolution * Generate comprehensive security analysis including private dependencies * Maintain complete visibility into your software supply chain Endor Labs generally respects package authentication and configuration settings and a package manager integration is usually not required to scan private packages successfully. * Use package manager integrations to simplify scanning when authentication to private repositories is not part of standard manifest or settings files. * Package manager integrations allow you to set custom repositories for each package ecosystem and the priority of each repository for scanning. To set up a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select **Add** next to the package manager configuration you want to add. 3. Select **Add Package Manager**. 4. Enter a **Name** for the integration. 5. Choose an authentication type and complete the required fields.
Enter your registry URL and static credentials.

AWS CodeArtifact authentication uses OIDC token federation. No static credentials are stored. Enter the following fields:

  • Domain: Name of your AWS CodeArtifact domain.
  • Domain Owner: AWS account ID that owns the domain.
  • Repository: Name of the CodeArtifact repository.
  • Target Role ARN: ARN of the IAM role Endor Labs assumes.
  • Allowed Audience: Audience value specified when you created the OIDC provider.
  • Region: AWS region of the repository.

See Configure integration with AWS CodeArtifact for setup instructions.
  1. Optionally, under Advanced, select Propagate this package manager to all child namespaces to share this integration with child namespaces.
  2. Click Add Package Manager.
### Test package manager integration You can test the connection to a configured package manager to verify that Endor Labs can reach the repository. To test the connection: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** in the package manager configuration you want to customize. 3. Click the vertical three dots of the package manager configured and select **Test Connection**. The integration does not perform authentication or authorization checks on the package manager repository. ### Edit package manager integration You can edit an existing package manager integration to update the name, repository URL, or authentication credentials. To edit a package manager integration: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Manage** next to the package manager you want to edit. 3. Click the vertical three dots on the configured integration you want to edit and select **Edit**. 4. You can modify the name, package manager URL, and credentials. 5. Click **Save Changes**. ## Package manager integration for SwiftPM using API Use endorctl to create a package manager resource for your private swift registry and authenticate using one of the following methods: * Basic authentication using username and password * Authentication token ### Basic authentication using username and password Run the following command to create a package manager resource and authenticate to Swift registry using basic authentication credentials with scope. Replace: * `namespace` with your namespace. * `username` with your username * `xxxx` with your password. * `scope` with your scope. For example, `"scope":"abc-corp"`. ```shell expandable theme={null} endorctl api create -r PackageManager -n -d ' { "meta": { "name": "test swift", "description": "setup swift registry with basic auth" }, "spec": { "swift": { "priority": 1, "url": "package manager url", "basic_auth": { "username": "username", "password": "xxxx" }, "scope": "scope" } }, "propagate": false }' ``` ### Authentication token Run the following command to create a package manager resource and authenticate to Swift registry using authentication token with scope. Replace: * `namespace` with your namespace * `token` with your Swift registry authentication token. * `scope` with your scope. For example, `"scope":"abc-corp"`. ```shell theme={null} endorctl api create -r PackageManager -n -d ' { "meta": { "name": "test swift", "description": "setup swift registry with token" }, "spec": { "swift": { "priority": 1, "url": "package manager url", "token": "authentication token", "scope": "scope" } }, "propagate": false } ' ``` ### Fetch package manager using API Run the following command to fetch the package manager using the UUID. ```bash theme={null} endorctl api get -r packageManager -n --uuid ``` ### Delete package manager using API Run the following command to delete the package manager using the UUID. ```bash theme={null} endorctl api delete -r packageManager -n --uuid ``` # SCM Integrations Source: https://docs.endorlabs.com/integrations/scm/index Connect source code management platforms for continuous monitoring. For information on integrating with Source Code Management (SCM) platforms like GitHub, GitLab, Azure DevOps, and Bitbucket, see [SCM Integrations](/setup-deployment/scm-integrations). Endor Labs provides native integrations with the following SCM platforms: * [**GitHub**](/setup-deployment/scm-integrations/github-app) * [**GitHub Pro**](/setup-deployment/scm-integrations/github-app-pro) * [**GitHub Enterprise Server**](/setup-deployment/scm-integrations/github-app/github-enterprise-app) * [**GitLab**](/setup-deployment/scm-integrations/gitlab-app) * [**Azure DevOps**](/setup-deployment/scm-integrations/azure-app) * [**Bitbucket Cloud**](/setup-deployment/scm-integrations/bitbucket-cloud) * [**Bitbucket Data Center**](/setup-deployment/scm-integrations/bitbucket-datacenter-app) # Set up Slack integration Source: https://docs.endorlabs.com/integrations/slack/index Learn how to integrate Slack with Endor Labs and receive finding notifications Integrate Endor Labs with Slack and automatically receive policy violations as notifications in your Slack channels. If you are using Slack for team communication and notifications, this integration helps you to seamlessly integrate Endor Labs into your organization's existing workflows. * [Create incoming webhooks in Slack](#create-incoming-webhooks-in-slack) * [Configure Slack integration](#configure-slack-integration) * [Associate an action policy with a Slack notification](#associate-an-action-policy-with-a-slack-notification) * [Manage Slack notification targets in Endor Labs](#manage-slack-notification-targets-in-endor-labs) * [Customize Slack notification templates](#customize-slack-notification-templates) * [Data model](#data-model) * [Run a scan](#run-a-scan) * [View notifications in Slack](#view-notifications-in-slack) ## Create incoming webhooks in Slack Create an incoming webhook to your Slack channel to enable Endor Labs to post notifications in the channel. The **Incoming Webhook** provides a unique URL to integrate your Slack channel in Endor Labs. We recommend you designate a channel in your Slack workspace for receiving Endor Labs notifications and create an incoming webhook for that channel. To create incoming webhooks in Slack: 1. Create a [Slack app](https://api.slack.com/apps?new_app=1) for Endor Labs or use an existing app. * Click **Create New App**. * Choose **From Scratch** and Enter a name for the app, for example, **Endor Labs**. * Select your workspace and click **Create App** * You can enter basic, install, or display information for your [Endor Labs app in Slack](https://api.slack.com/apps?new_app=1). * In **Display Information**, you can upload a logo and customize App colours to distinguish the Endor Labs App on the Slack workspace. * Click **Save Changes**. 2. Under **Features**, select **Incoming Webhooks**, then turn on **Activate Incoming Webhooks**. 3. Refresh the page and click **Add New Webhook to Workspace**. 4. Select a channel to receive Endor Labs findings in **Post to**, then select **Authorize**. If you need to add the incoming webhook to a private channel, you must first be in that channel. 5. From **Settings**, copy the webhook URL under **Webhook URLs for Your Workspace**. Keep this URL handy to enter in Endor Labs. For details on creating incoming webhooks in Slack, see [Slack Integration](https://api.slack.com/messaging/webhooks) ## Configure Slack integration To configure Slack integration, follow these steps: 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Add** on the **Slack** card. If you already have a Slack integration, click **Manage** instead. 3. Click **Add Notification Integration** to open the **Send Notifications to Slack** dialog. 4. Enter a **Name** and **Description** for this integration. 5. In **Webhook URL**, enter the incoming webhook URL you copied from Slack. 6. Optional: select **Propagate this notification target to all child namespaces** to make this integration available in child namespaces. 7. Click **Add Notification Integration** to save the integration. ### Associate an action policy with a Slack notification Users can create action policies to send a Slack notification when a scan matches policy conditions. For example, if there is a critical or high vulnerability, send the findings to Slack. To send a Slack message when a scan produces matching findings, create an action policy with a **Send Notification** action that targets your Slack integration. For the full procedure, see [Create an action policy](/platform-administration/policies/action-policies). The Slack-specific choices are: * Under **Choose an Action**, select **Send Notification**. * From **Select notification targets**, choose the Slack integration you created. From **Select aggregation type**, choose how findings are grouped into notifications. * **None (Notify for each Finding)** sends a separate notification for each finding. * **Project** sends a single notification for all findings in a project. * **Dependency** sends a notification for every dependency. * **Dependency per Package Version** sends a notification for every unique combination of dependency and package version. Slack messages show the top three findings from the highest available severity level. If fewer than three findings exist, only those appear. ### Manage Slack notification targets in Endor Labs You can view and manage the Endor Labs Slack notification targets created for a project. 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Manage** on the **Slack** card. You can view all your created notification targets for Slack. 3. To edit a notification target, click the vertical three dots and choose **Edit Notification Integration**. 4. To delete a notification target, click the vertical three dots and choose **Delete Notification Integration**. ### Customize Slack notification templates Endor Labs provides a default standard template with standard information for the Slack message. You can use the default template or you can choose to edit and customize this template to fit your organization's specific requirements. You can also create custom templates using [Go Templates](https://pkg.go.dev/text/template). 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Manage** on the **Slack** card to view the configured notification integrations. 3. Choose one, click the vertical three dots on the right side, and click **Edit Template**. 4. Make required changes to any of the following templates and click **Save Template**. * **Open** - This template applies when Endor Labs raises new notifications. * **Update** - This template applies when an existing notification updates, such as when findings change. 5. Click **Restore to Default** to revert the changes. 6. Use the download icon on the top right corner to download this template. 7. Use the copy icon to copy the information in the template. ### Data model To create custom templates for Slack messages, you must understand the data supplied to the template. See the protobuf specification `NotificationData` message used for the templates. To understand Project, Finding, PackageVersion, and RepositoryVersion definitions used in this protobuf specification, see: * [Project resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#project) * [Finding resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#finding) * [PackageVersion resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#packageversion) * [RepositoryVersion resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#repositoryversion) See the following specification to understand a few additional functions available to the template. You can access these functions by using their corresponding keys. ## Run a scan Run the endorctl scan on your configured projects. See [endorctl scan commands](/developers-api/cli/commands/scan) for more information. ### View notifications in Slack View Endor Labs' findings in Slack and take remedial actions. * Sign in to Slack and view the notifications on the configured channel. * You can view the top 3 findings by their severity level. Click **View All** to see all the findings in Endor Labs. View notifications in Slack # Third-party integrations Source: https://docs.endorlabs.com/integrations/third-party-integrations/index Integrate Endor Labs with third-party security and vulnerability management platforms. Endor Labs integrates with third-party security platforms, enabling you to consolidate security data, unify vulnerability management, and streamline your security workflows. These integrations allow third-party platforms to retrieve security findings, packages, projects, and repository data from Endor Labs through the API. Third-party integrations can retrieve the following data types from Endor Labs: ## How third-party integrations work Third-party integrations with Endor Labs use a pull-based model where the external platform connects to the Endor Labs API to retrieve security data. To set up an integration: 1. Create [API credentials](/platform-administration/api-keys) in Endor Labs with read-only access. 2. Configure the connector in the third-party platform with your Endor Labs credentials. 3. Schedule data synchronization to keep the platforms in sync. ## Supported platforms The following third-party platforms have integrations available with Endor Labs: * [ArmorCode](#armorcode) * [Brinqa](#brinqa) * [Nucleus Security](#nucleus-security) * [Wiz](#wiz) ### ArmorCode ArmorCode is an Application Security Posture Management (ASPM) platform that helps organizations consolidate security findings from multiple tools, prioritize vulnerabilities, and automate remediation workflows. Integrate ArmorCode with Endor Labs to retrieve security findings, packages, projects, and repository data for centralized security management and correlation with other security tools. For more information, refer to [ArmorCode integration](https://www.armorcode.com/blog/armorcode-endor-labs-integration). ### Brinqa Brinqa is a unified vulnerability management (UVM) platform that helps organizations consolidate security data from multiple sources to construct a comprehensive view of their attack surface. Integrate Brinqa with Endor Labs to import package, project, repository, and security findings data for centralized risk management and compliance reporting. For more information, refer to [Brinqa integration](https://docs.brinqa.com/docs/connectors/endor-labs/). ### Nucleus Security Nucleus Security is a vulnerability management platform that helps organizations aggregate, correlate, and prioritize vulnerabilities from multiple security tools. Integrate Nucleus Security with Endor Labs to import security findings, packages, and project data for centralized vulnerability management and remediation tracking. ### Wiz Wiz is a cloud-native application protection platform (CNAPP) that helps organizations correlate code and cloud risk in the Wiz Security Graph. Integrate Wiz with Endor Labs by configuring the [Wiz exporter](/integrations/data-exporters/export-to-wiz), which pushes SCA and SAST findings from scheduled default-branch scans into Wiz. # Set up Vanta integration with Endor Labs Source: https://docs.endorlabs.com/integrations/vanta/index Learn how to integrate Vanta with Endor Labs and automate compliance requirements Vanta enables organizations to manage risk by automating compliance and streamlining security reviews. Integrate Vanta with Endor Labs to view security findings in real-time and accelerate your security audit processes. To integrate Endor Labs with Vanta: * [Create an application in Vanta](#create-an-application-in-vanta) * [Create resources in Vanta](#create-resources-in-vanta) * [Configure Vanta integration](#configure-vanta-integration) * [Associate an action policy with a Vanta notification](#associate-an-action-policy-with-a-vanta-notification) * [Manage Vanta notification targets in Endor Labs](#manage-vanta-notification-targets-in-endor-labs) * [Run a scan](#run-a-scan) * [Findings exported to Vanta](#findings-exported-to-vanta) * [View findings in Vanta](#view-findings-in-vanta) ## Create an application in Vanta Create an application in Vanta so that Endor Labs can authenticate and export vulnerability findings to Vanta. The app requires `connectors.self:write-resource` and `connectors.self:read-resource scopes` to export vulnerabilities. 1. Sign in to Vanta as an Administrator. 2. Click **Settings** on the top navigation bar. 3. Select **Developer Console**. Vanta Developer Console 4. Click **Create**. 5. Select **Build Integrations**. 6. Enter a name and description for your application. 7. Select the **App Visibility** as **Private** and click **Create**. Create Vanta Integration 8. Select the **Application Category** as **Vulnerability Scanner**. 9. Click **Generate Client Secret** to generate the OAuth client secret. OAuth Client ID appears. Copy the OAuth Client ID and the client secret and have them handy. You must enter this data in Endor Labs to configure the Vanta integration. Build Vanta Integration 10. Click **Save**. ### Create resources in Vanta To successfully ingest security data and create notifications, map the Endor Labs attributes to resource types in Vanta. 1. Sign in to Vanta. 2. Navigate to **Settings** and click **Developer Console**. 3. Select your application and click **Resources**. 4. Click **Create Resource** and create the following resources to successfully map Endor Labs data into Vanta. * Enter the **Resource Type** as `Vulnerable Component` (mandatory) and select the **Base Resource Type** as **VulnerableComponent**. Create Resource * Enter the **Resource Type** as `Package Vulnerability` (optional) and select the **Base Resource Type** as **PackageVulnerabilityConnectors**. * Enter the **Resource Type** as `Static Code Analysis` (optional) and select the **Base Resource Type** as **StaticAnalysisCodeVulnerabilityConnectors**. Provide the **Static Code Analysis** resource type if you want to export exposed secrets in your first party code to Vanta. You can view the schema generated for all the resource types. Copy the **Resource ID** of the generated resources and have them handy. You must enter this data in Endor Labs to configure the Vanta integration. Vanta Resource IDs ## Configure Vanta integration Set up Endor Labs integration with Vanta. Prerequisites: Make sure you have the client ID, client secret, and the resource IDs from Vanta handy. 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Add** for **Vanta**. 3. Click **Add Notification Integration**. Add Notification Integration 4. Enter a name and description for this integration. 5. Enter the **CLIENT ID** and **CLIENT SECRET** that you generated on Vanta. 6. Under **Vanta Resources**, enter the Resource IDs for VULNERABILITY COMPONENT, PACKAGE VULNERABILITY, and STATIC CODE ANALYSIS VULNERABILITY from Vanta. **Vulnerable Component** is mandatory. You must enter either one of the **Package Vulnerability** or **Static Code Analysis Vulnerability** resource types. 7. Click **Add Notification Integration**. ### Associate an action policy with a Vanta notification Users can create action policies to execute a recommended action when a scan violates a policy. For example, if there is a critical or high vulnerability, Endor Labs exports those vulnerabilities to Vanta to ensure compliance adherence. While creating an action policy, configure the following settings: * Select **Choose an Action** as **Send Notification**. * From **SELECT NOTIFICATION TARGETS**, choose the Vanta integration notification that you created. * Choose an [**Aggregation type**](/platform-administration/policies/action-policies#aggregation-types-for-notifications) for notifications. For integrating with Vanta, we recommend you choose **Project**. * From **Assign Scope**, include the project tags in **INCLUSIONS** to apply this policy to a project. See [Create an action policy](/platform-administration/policies/action-policies) for more details. ### Manage Vanta notification targets in Endor Labs You can view and manage the Endor Labs Vanta notification targets created for a project. 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Manage** for **Vanta**. You can view all your created notification targets for Vanta. 3. To edit a notification target, click the vertical three dots and choose **Edit Notification Integration**. 4. To delete a notification target, click the vertical three dots and choose **Delete Notification Integration**. ## Run a scan Run the endorctl scan on your configured projects. See [endorctl scan commands](/developers-api/cli/commands/scan) for more information. ### Findings exported to Vanta Endor Labs sends the following findings to Vanta: * third-party open-source vulnerabilities * secrets exposed in the first-party code Endor Labs exports these findings as **Package Vulnerabilities** and **Static Code Analysis Vulnerabilities** in Vanta and associates them with a **Vulnerable Component** (that is the Repository Version) in Vanta. Exporting findings generated on the Git repository security posture of an organization are not supported. ## View findings in Vanta View Endor Labs' findings in Vanta and take remedial actions. 1. Sign in to Vanta. 2. Select **Tests** to view notifications. 3. Select the integration that you created in the **Integration** filter to view notifications from Endor Labs. View Endor Labs Results in Vanta 4. Select a notification to view all findings associated with the Endor Labs policy. View notification in Vanta 5. Click on a finding to view more details in Endor Labs. For example, if you create an action policy to notify critical vulnerabilities and configure it to a Vanta notification target, you can see the exports as **Critical vulnerabilities identified in code repositories are addressed** under **Tests** in Vanta. Vanta classifies the tests by the severity of the exported findings. # Set up integrations using webhooks Source: https://docs.endorlabs.com/integrations/webhooks/index Learn how to create webhooks and enable custom integrations with Endor Labs application Webhooks enable real-time communication between different systems or applications over the internet. They allow one application to send data to another application as soon as a specific event or a trigger occurs. Use webhooks to integrate Endor Labs with applications such as Slack, Microsoft Teams or more, and instantly get notified about projects when scans violate your configured policies. When events occur, Endor Labs sends HTTPS POST requests to URLs of your configured events, with all the information you need. ## Configure a webhook integration Set up a custom integration with Endor Labs webhooks. 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Add** on the **Webhook** card. If you already have a webhook integration, click **Manage** instead. 3. Click **Add Notification Integration**. **Send Notifications to Webhook** appears. 4. Enter a **Name** and **Description** for this integration. 5. In **URL endpoint for webhook**, enter the URL of your webhook receiver. If your webhook receiver accepts traffic only from allowlisted IP addresses, see [Ingress rules for restricted environments](/best-practices/troubleshooting/firewall-rules#ingress-rules-for-restricted-environments) to allow notifications from Endor Labs. 6. Choose an **Auth method** of **None**, **Basic**, or **API Key**, then enter its credentials. Basic authentication uses **Username** and **Password**. API key authentication uses **API Key**. Make sure the credentials grant permission to post to your receiver. 7. If you chose **Basic** or **API Key**, HMAC signing is on by default. Enter an **HMAC Shared Key**, or select **Disable HMAC Integration Check** to turn it off. When HMAC is on, Endor Labs signs the request body and sends the signature in the `X-Endor-HMAC-Signature` header so your receiver can verify that the request is authentic. HMAC is not available for **None** auth. 8. Optional: Under **Custom Headers**, click **Add Header**, then enter a **Header name** and **Header value**. You can add up to 20 headers. Use custom headers to pass vendor-specific API keys required by your webhook receiver. Endor Labs includes custom headers in every webhook request, regardless of the authentication method used. 9. Optional: Select **Propagate this notification target to all child namespaces** to make this integration available in child namespaces. 10. Click **Add Notification Integration** to save the integration. ### Associate an action policy with the webhook You can create action policies to trigger webhook notifications when a scan matches policy conditions. For example, send a webhook notification when there is a critical or high vulnerability. To send a webhook when a scan produces matching findings, create an action policy with a **Send Notification** action that targets your webhook integration. For the full procedure, see [Create an action policy](/platform-administration/policies/action-policies). The webhook-specific choices are: * Under **Choose an Action**, select **Send Notification**. * From **Select notification targets**, choose the webhook integration you created. From **Select aggregation type**, choose how findings are grouped into notifications. * **None (Notify for each Finding)** sends a separate notification for each finding. * **Project** sends a single notification for all findings in a project. * **Dependency** sends a notification for every dependency. * **Dependency per Package Version** sends a notification for every unique combination of dependency and package version. ## Endor Labs webhook payload Endor Labs provides the following webhook payload, that you can customize for your needs. You can view all possible payload information in [GetFindings REST API endpoint](/api-reference/findingservice/listfindings). Expand the `spec` section in the API response to view all the information. See the following sample notification payload. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ```json expandable theme={null} { "data": { "message": "4 findings discovered for project endorlabs/monorepo", "projectURL": "https://app.endorlabs.com/t//projects/", "policy": { "name": "Webhook vuln", "url": "https://app.endorlabs.com/t//policies/actions?filter.default=Webhook+vuln" }, "findings": [ { "uuid": "550e8400-e29b-41d4-a716-446655440000", "description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service", "severity": "FINDING_LEVEL_MEDIUM", "dependency": "semver@7.5.0", "package": "endorlabs-vscode-extension@1.5.0", "findingURL": "https://app.endorlabs.com/t//findings/550e8400-e29b-41d4-a716-446655440000" }, { "uuid": "550e8400-e29b-41d4-a716-446655440001", "description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service", "severity": "FINDING_LEVEL_MEDIUM", "dependency": "semver@7.3.8", "package": "endorlabs-vscode-extension@1.5.0", "findingURL": "https://app.endorlabs.com/t//findings/550e8400-e29b-41d4-a716-446655440001" }, { "uuid": "550e8400-e29b-41d4-a716-446655440002", "description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service", "severity": "FINDING_LEVEL_MEDIUM", "dependency": "semver@5.7.1", "package": "endorlabs-vscode-extension@1.5.0", "findingURL": "https://app.endorlabs.com/t//findings/550e8400-e29b-41d4-a716-446655440002" }, { "uuid": "550e8400-e29b-41d4-a716-446655440003", "description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service", "severity": "FINDING_LEVEL_MEDIUM", "dependency": "semver@6.3.0", "package": "endorlabs-vscode-extension@1.5.0", "findingURL": "https://app.endorlabs.com/t//findings/550e8400-e29b-41d4-a716-446655440003" } ] } } ``` In the payload, replace `` and `` with the values from your Endor Labs tenant. The identifier in each `findingURL` matches that finding's `uuid`. ### Payload variations by notification event Endor Labs sends a webhook for three notification events. The `data.message` text and the presence of `data.findings` change with the event. * **Findings discovered**: Endor Labs sends the payload shown above. The `data.message` field reads ` findings discovered for project ` and `data.findings` lists every finding. * **New findings added**: A later scan finds additional findings. The `data.message` field reads ` new findings discovered for project ` and `data.findings` lists only the new findings. * **Findings resolved**: A scan resolves all findings. The `data.message` field reads `All findings resolved for project ` and the payload omits the `data.findings` array. The `data.policy` object is present only when an action policy triggers the notification. The following example shows the payload when a later scan adds new findings. The `data.findings` array lists only the new findings. ```json expandable theme={null} { "data": { "message": "2 new findings discovered for project endorlabs/monorepo", "projectURL": "https://app.endorlabs.com/t//projects/", "policy": { "name": "Webhook vuln", "url": "https://app.endorlabs.com/t//policies/actions?filter.default=Webhook+vuln" }, "findings": [ { "uuid": "550e8400-e29b-41d4-a716-446655440004", "description": "GHSA-jf85-cpcp-j695: Prototype Pollution in lodash", "severity": "FINDING_LEVEL_CRITICAL", "dependency": "lodash@4.17.4", "package": "endorlabs-vscode-extension@1.5.0", "findingURL": "https://app.endorlabs.com/t//findings/550e8400-e29b-41d4-a716-446655440004" }, { "uuid": "550e8400-e29b-41d4-a716-446655440005", "description": "GHSA-35jh-r3h4-6jhm: Command Injection in lodash", "severity": "FINDING_LEVEL_HIGH", "dependency": "lodash@4.17.4", "package": "endorlabs-vscode-extension@1.5.0", "findingURL": "https://app.endorlabs.com/t//findings/550e8400-e29b-41d4-a716-446655440005" } ] } } ``` The following example shows the payload when a scan resolves all findings. The payload omits the `data.findings` array. ```json expandable theme={null} { "data": { "message": "All findings resolved for project endorlabs/monorepo", "projectURL": "https://app.endorlabs.com/t//projects/", "policy": { "name": "Webhook vuln", "url": "https://app.endorlabs.com/t//policies/actions?filter.default=Webhook+vuln" } } } ``` ## Use Endor Labs webhooks to integrate with Slack If you use Slack as a collaborative tool, integrate Slack channels using webhooks in Endor Labs to publish notifications as messages in the respective channels. * [Configure a webhook integration](#configure-a-webhook-integration) * [Endor Labs webhook payload](#endor-labs-webhook-payload) * [Use Endor Labs webhooks to integrate with Slack](#use-endor-labs-webhooks-to-integrate-with-slack) * [Create incoming webhooks in Slack](#create-incoming-webhooks-in-slack) * [Customize webhook notification templates](#customize-webhook-notification-templates) * [Data model](#data-model) * [Webhook handler example for Slack](#webhook-handler-example-for-slack) ### Create incoming webhooks in Slack Create an incoming webhook to your Slack channel to enable Endor Labs to post notifications in the channel. The webhook provides a unique URL for integrating the channel in Endor Labs. To send messages into Slack using incoming webhooks, see [Slack Integration](https://api.slack.com/messaging/webhooks) If you have already created an incoming webhook in the channel, copy the unique URL and integrate the channel in Endor Labs. ### Customize webhook notification templates Endor Labs provides you with a default template with standard information for the webhook message. You can use the default template or you can choose to edit and customize this template to fit your organization's specific requirements. You can also create your own custom templates using [Go Templates](https://pkg.go.dev/text/template). 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Manage** on the **Slack** card to view the configured notification integrations. 3. Choose one, click the ellipsis on the right side, and click **Edit Template**. 4. Make required changes to any of the following templates and click **Save Template**. * **Open** - This template applies when Endor Labs raises new notifications. * **Update** - This template applies when an existing notification updates, such as when findings change. * **Resolve** - This template applies when all findings reported by the notification resolve. 5. Click **Restore to Default** to revert the changes. 6. Use the download icon on the top right corner to download this template. 7. Use the copy icon to copy the information in the template. ### Data model To create custom templates for Webhook notifications, you must understand the data supplied to the template. See the protobuf specification `NotificationData` message used for the templates. To understand Project, Finding, PackageVersion and RepositoryVersion definitions used in this protobuf specification, see: * [Project resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#project) * [Finding resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#finding) * [PackageVersion resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#packageversion) * [RepositoryVersion resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#repositoryversion) See the following specification to understand a few additional functions available to the template. You can access these functions by using their corresponding keys. ### Webhook handler example for Slack Create a webhook handler or a cloud function to receive webhook requests generated by Endor Labs, authorize the request, and post messages to your Slack channel. See the following code sample hosted as a cloud function or a webhook handler. ```go expandable theme={null} // Package p contains an HTTP Cloud Function that receives Endor Labs webhook // notifications, verifies the HMAC signature, and posts a message to Slack. package p import ( "bytes" "crypto/hmac" "crypto/sha256" "encoding/base64" "encoding/json" "fmt" "io" "log" "net/http" ) // WebhookMessage is the default Endor Labs webhook payload. type WebhookMessage struct { Data Payload `json:"data"` } type Payload struct { Message string `json:"message"` ProjectURL string `json:"projectURL"` Policy Policy `json:"policy"` Findings []Finding `json:"findings"` } type Finding struct { UUID string `json:"uuid"` Description string `json:"description"` Severity string `json:"severity"` Dependency string `json:"dependency,omitempty"` Package string `json:"package,omitempty"` RepositoryVersion string `json:"repositoryVersion,omitempty"` FindingURL string `json:"findingURL"` } type Policy struct { Name string `json:"name"` URL string `json:"url"` } // hmacSharedKey is the HMAC Shared Key you configured on the webhook integration. const hmacSharedKey = "" // HandleWebhook verifies the request signature, then posts the notification to Slack. func HandleWebhook(w http.ResponseWriter, r *http.Request) { // Read the raw body first. Endor Labs signs these exact bytes, so verify the // signature before decoding the JSON. body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "unable to read request body", http.StatusBadRequest) return } // Endor Labs signs the raw body with HMAC-SHA256 and sends the // base64-encoded signature in the X-Endor-HMAC-Signature header. if !validSignature(body, r.Header.Get("X-Endor-HMAC-Signature"), hmacSharedKey) { http.Error(w, "invalid signature", http.StatusUnauthorized) return } var message WebhookMessage if err := json.Unmarshal(body, &message); err != nil { http.Error(w, "unable to decode payload", http.StatusBadRequest) return } text := fmt.Sprintf("%s which violates policy %s", message.Data.Message, message.Data.Policy.Name) if err := sendMessageToSlack(text); err != nil { log.Printf("unable to post to Slack: %v", err) http.Error(w, "unable to post to Slack", http.StatusInternalServerError) return } } // validSignature recomputes the HMAC over the raw body and compares it against // the received signature in constant time. func validSignature(body []byte, receivedSignature, sharedKey string) bool { mac := hmac.New(sha256.New, []byte(sharedKey)) mac.Write(body) expected := base64.StdEncoding.EncodeToString(mac.Sum(nil)) return hmac.Equal([]byte(expected), []byte(receivedSignature)) } // sendMessageToSlack posts a message to a Slack incoming webhook. func sendMessageToSlack(text string) error { // Replace this with the incoming webhook URL from your Slack app. slackWebhookURL := "https://hooks.slack.com/services/" body, err := json.Marshal(map[string]string{"text": text}) if err != nil { return err } resp, err := http.Post(slackWebhookURL, "application/json", bytes.NewReader(body)) if err != nil { return err } defer resp.Body.Close() return nil } ``` # Documentation MCP server Source: https://docs.endorlabs.com/introduction/docs-mcp-server/index Connect the Endor Labs documentation MCP server to your AI tools for accurate, up-to-date answers about Endor Labs. The Endor Labs documentation MCP server gives your AI tools direct access to the complete Endor Labs documentation. Instead of relying on outdated training data, your AI assistant can search and read current documentation in real time. Endor Labs hosts the documentation MCP server at `https://docs.endorlabs.com/mcp` using HTTP transport. You do not need authentication, API keys, or local installation. This page covers the **documentation** MCP server for searching Endor Labs docs. For the **security scanning** MCP server that scans your code for vulnerabilities, see [MCP server](/setup-deployment/mcp). ## What the documentation MCP server provides The MCP server provides the following tools that AI applications use: * **Search documentation**: Searches across all Endor Labs documentation to find relevant content, returning snippets with titles and direct links. * **Query docs filesystem**: Reads and navigates a virtual filesystem of documentation pages using shell-style commands like `rg`, `cat`, `head`, and `tree`. Your AI system decides when to leverage these tools and can independently query the documentation as it generates a response, even without a direct prompt to do so. ## Connect the documentation MCP server Click **Install in Cursor** to add the documentation MCP server. To manually configure the MCP server, add the following JSON to a `.cursor/mcp.json` file in the root of your repository. ```json theme={null} { "mcpServers": { "endor-docs": { "url": "https://docs.endorlabs.com/mcp" } } } ``` You can also use the command palette. Press `Cmd + Shift + P` (or `Ctrl + Shift + P` on Windows and Linux), search for **MCP: Add Server**, and enter the URL `https://docs.endorlabs.com/mcp`. Click **Install in VS Code** to add the documentation MCP server. To manually configure the MCP server, create a `.vscode/mcp.json` file in the root of your repository and add the following JSON. ```json theme={null} { "servers": { "endor-docs": { "type": "http", "url": "https://docs.endorlabs.com/mcp" } } } ``` Add the Endor Labs documentation MCP server as a custom connector in the Claude web interface. 1. Go to **Settings** > **Connectors**. 2. Select **Add custom connector**. 3. Enter the following details: * **Name**: `Endor Labs Docs` * **URL**: `https://docs.endorlabs.com/mcp` 4. Select **Add**. 5. When using Claude, select the attachments button (the plus icon) and choose the **Endor Labs Docs** connector. For more information, refer to the [Claude MCP documentation](https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai). Run the following command to add the documentation MCP server to Claude Code. ```bash theme={null} claude mcp add --transport http endor-docs https://docs.endorlabs.com/mcp ``` Run the following command to verify the connection. ```bash theme={null} claude mcp list ``` For more information, refer to the [Claude Code documentation](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp). Run the following command to add the documentation MCP server to Gemini CLI. ```bash theme={null} gemini mcp add --transport http endor-docs https://docs.endorlabs.com/mcp ``` Run the following command to verify the connection. ```bash theme={null} gemini mcp list ``` For more information, refer to the [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli). The documentation MCP server does not require authentication. However, Codex automatically detects OAuth support on HTTP MCP servers and attempts an OAuth flow that fails. To work around this, provide a placeholder bearer token environment variable when adding the server. Run the following commands to add the documentation MCP server to OpenAI Codex. ```bash theme={null} export ENDOR_DOCS_KEY="dummy" codex mcp add endor-docs --url https://docs.endorlabs.com/mcp --bearer-token-env-var ENDOR_DOCS_KEY ``` Set the `ENDOR_DOCS_KEY` environment variable in your shell before starting Codex. Add `export ENDOR_DOCS_KEY="dummy"` to your shell profile (such as `~/.zshrc` or `~/.bashrc`) so it persists across sessions. Run the following command to verify the connection. ```bash theme={null} codex mcp list ``` You can also use `/mcp` in the Codex TUI to view active MCP servers. Alternatively, add the server directly to `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.endor-docs] url = "https://docs.endorlabs.com/mcp" bearer_token_env_var = "ENDOR_DOCS_KEY" enabled = true ``` Ensure that you set the `ENDOR_DOCS_KEY` environment variable in your shell profile before starting Codex. Add the Endor Labs documentation MCP server to Devin through the MCP Marketplace. 1. Navigate to [Settings > MCP Marketplace](https://app.devin.ai/settings/mcp-marketplace) in Devin. 2. Select **Add Your Own** to add a custom MCP server. 3. Under **HTTP Configuration**, enter the URL `https://docs.endorlabs.com/mcp`. 4. Select **Save Changes**. The documentation MCP server does not require secrets or authentication. Add the Endor Labs documentation MCP server to Augment Code. 1. Open the Augment Code extension in Visual Studio Code. 2. Select the **Settings** icon in the upper right of the Augment panel. 3. In the **MCP** section, select **Import from JSON** or **+** to add a server. 4. Paste the following configuration: ```json theme={null} { "mcpServers": { "endor-docs": { "url": "https://docs.endorlabs.com/mcp" } } } ``` Alternatively, select **+**, set **Name** to `endor-docs`, and set the **URL** to `https://docs.endorlabs.com/mcp`. Add the Endor Labs documentation MCP server to IntelliJ IDEA through GitHub Copilot. 1. Open **GitHub Copilot Chat** and switch to **Agent** mode. 2. Select **Configure Tools**, then select **+ Add More Tools...** to open `mcp.json`. 3. Add the following configuration: ```json theme={null} { "servers": { "endor-docs": { "type": "http", "url": "https://docs.endorlabs.com/mcp" } } } ``` 4. Save and close `mcp.json`. Switch from **Agent** to **Ask** mode and back to **Agent** mode to reload the MCP server. Add the Endor Labs documentation MCP server to Google Antigravity. 1. On the agent panel, click **...**, then select **MCP Servers** > **Manage MCP Servers**. 2. Click **View raw config** to open `mcp_config.json`. 3. Add the following configuration: ```json theme={null} { "mcpServers": { "endor-docs": { "serverUrl": "https://docs.endorlabs.com/mcp" } } } ``` 4. Save the file. Antigravity automatically reloads the MCP server configuration. For more information, refer to the [Google Antigravity documentation](https://antigravity.google/docs/mcp). Add the following configuration to your `opencode.json` file. ```json theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "endor-docs": { "type": "remote", "url": "https://docs.endorlabs.com/mcp" } } } ``` Run the following command to verify the connection. ```bash theme={null} opencode mcp list ``` For any MCP-compatible tool, use the following server URL. ```text theme={null} https://docs.endorlabs.com/mcp ``` The documentation MCP server uses **HTTP transport**. Configure your tool with the URL above. You do not need authentication headers or API keys. If your tool uses a JSON configuration file, use one of the following formats. For tools that use `mcpServers` as the top-level key: ```json theme={null} { "mcpServers": { "endor-docs": { "url": "https://docs.endorlabs.com/mcp" } } } ``` For tools that use `servers` as the top-level key: ```json theme={null} { "servers": { "endor-docs": { "type": "http", "url": "https://docs.endorlabs.com/mcp" } } } ``` ## Verify the connection After connecting, test the MCP server by asking your AI tool a question about Endor Labs. For example: * "How do I configure a scan profile in Endor Labs?" * "What package managers does Endor Labs support?" * "How do I set up GitHub Actions with Endor Labs?" Your AI tool should search the Endor Labs documentation and provide an answer with references to specific documentation pages. ## Use with the security scanning MCP server The documentation MCP server works alongside the [Endor Labs security scanning MCP server](/setup-deployment/mcp). You can connect both to the same AI tool. * The **documentation MCP server** answers questions about Endor Labs features, configuration, and usage. * The **security scanning MCP server** scans your code for vulnerabilities, leaked secrets, and security issues. Your AI assistant selects the appropriate server based on the conversation context. Connecting both servers enables full access to Endor Labs capabilities. # Endor Labs user interface Source: https://docs.endorlabs.com/introduction/endor-labs-ui/index Understand Endor Labs user interface and how to navigate through it. The Endor Labs user interface prioritizes efficient navigation, with the primary menu located in the left sidebar. To access the Endor Labs user interface, sign into [Endor Labs](https://app.endorlabs.com/login) with your credentials. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. Endor UI The Endor Labs user interface page has three main sections: * **Left sidebar**: The left sidebar provides quick access to different modules and features of the platform. * **Main content panel**: This section displays the primary information and data relevant to the selected module. * **Right sidebar**: This section provides the detail drawers of the selected view in the main content area offering quick access to supplementary data. ## Home The **Home** gives a quick and clear view of your project's security status. Home See [Dashboard Documentation](/inventory-insights/dashboards) for more information. ## Projects The **Projects** page helps you manage and track your software packages and dependencies. You can: * Search and filter projects across different namespaces. * View findings associated with each project to assess security risks. * Add new projects to your workspace by clicking the **Add Project** option. Projects See [Manage Projects](/inventory-insights/projects) for more information. ## Findings The **Findings** page helps you to identify and analyze security risks across different areas. Findings See [View Findings](/inventory-insights/findings) for more information. ## Inventory Inventory provides a centralized catalog of assets discovered in your workspace (for example, dependencies, artifacts, and AI models). The following pages are available in **Inventory**. ### Dependencies The **Dependencies** page gives detailed insights into package dependencies. You can: * Search and filter dependencies based on specific criteria. * Export filtered dependency data as a CSV file for further analysis. Dependencies See [Dependencies](/inventory-insights/dependencies) for more information. ### AI Models The **AI Models** page helps you find and evaluate AI models used in your projects, providing insights into their usage, status, and impact. Endor Labs flags these models during scans and evaluates them for risks and operational security. AI model See [AI model findings](/secure-ai-coding/ai-model-discovery) for more information. ### Artifacts The **Artifacts** page displays signed artifacts along with detailed provenance data. This helps ensure that artifacts are securely generated, traced, and verified within the CI/CD pipeline, reducing the risk of tampering or unauthorized modifications. Artifacts See [Sign artifacts](/scan/containers/artifact-signing) for more information. ### Licenses The **Licenses** page lets you view and manage license information across your projects for legal and compliance review. You can see the license name, OSI approval status, license type, and project count for each dependency, edit license data, and generate Notice reports for distribution. Licenses See [Licenses](/inventory-insights/licenses) for more information. ### Hugging Face organizations The **Hugging Face organizations** page lets you connect a Hugging Face organization to Endor Labs and scan all its AI models. Endor Labs continuously scans models and scores them for security, activity, popularity, and quality, surfacing them in your inventory alongside your other projects. Hugging Face organizations See [Hugging Face organization models](/secure-ai-coding/huggingface-organization) for more information. ## Containers The **Containers** page lists container images Endor Labs found through scans. You can see how each image is used, how many versions were scanned, and how findings compare across tags or digests. You can: * Search and filter images to focus on specific registries, projects, or risk levels. * Select a container image to review its versions, container reachability, linked projects, and finding counts. Containers list in the Endor Labs user interface See [Container inventory](/scan/containers/container-findings) for more information. ## SBOM Hub The **SBOM Hub** helps you manage and track Software Bill of Materials (SBOMs) in one place. Select an SBOM to view the list of dependencies, their visibility, source availability, Endor scores, and whether Endor Labs classifies each package version as malware. You can: * Import SBOMs easily using the **Import SBOM** button. * Use filters to narrow down searches and find specific SBOMs quickly. SBOM Hub See [Manage SBOMs](/inventory-insights/sbom) for more information. ## Discovery The following pages are available in **Discovery**. ### OSS packages The **OSS Packages** page allows users to find and track open-source dependencies, identifying security risks and licensing concerns. OSS Packages See [Open Source Packages](/discover/open-source-packages) for more information. ### Vulnerabilities Vulnerabilities are weaknesses in software components that attackers can exploit to compromise the confidentiality, integrity, or availability of an application. The **Endor Vulnerability Database** provides a centralized view of known security issues across open-source ecosystems. It supports searching by standard identifiers like CVE, GHSA, MAL, and PySEC. It also surfaces key metadata such as severity, affected versions, malware reasoning, and fix information to help teams assess risk before introducing a dependency into a project. Vulnerabilities See [Endor Labs vulnerability database](/discover/vulnerability-db) for more information. ### AI models The **AI Models** page is a search tool to find and explore AI models available within the platform. This page displays the top AI models from Hugging Face with information like model name, security score, activity score, operational score, and more. Find AI model See [AI Models](/secure-ai-coding/ai-model-discovery) for more information. ## Package Firewall The **Package Firewall** page provides real-time protection against malicious packages during software installations. Positioned between your package managers and public registries, it intercepts every installation request and blocks known malicious packages before they reach your environment, while allowing safe packages through unchanged. Package Firewall See [Package Firewall](/package-firewall) for more information. ## Reports The **Reports** page lets you export analytics and findings data from Endor Labs for offline review, audits, and external workflows. You can generate two types of reports: * **Analytics reports**: A high-level view of vulnerability trends over time, including newly discovered and resolved vulnerabilities broken down by severity and remediation patterns. * **Findings reports**: A detailed export of individual security findings with severity, affected components, fix availability, reachability, and policy signals. See [Reports](/inventory-insights/reports) for more information. ## Policies and rules The **Policies & Rules** page allows users to define security and compliance policies for their projects. It includes: * **Finding Policies**: These policies enable users to detect and categorize security issues within their projects. Administrators can create custom finding policies to address specific security needs and ensure the detection of vulnerabilities. * **Exception Policies**: These policies allow users to define conditions under which they can mark certain findings as exceptions. This helps in filtering out known issues that the team accepted as risks. * **Action Policies**: These policies enable the automation of responses to policy violations. * **Remediation Policies**: These policies define guidelines for fixing identified security issues. * **Secret Rules**: These rules detect and manage exposed secrets within the codebase. They help in identifying sensitive information. * **SAST Rules**: These rules enable users to perform automated analysis on their source code to detect potential security vulnerabilities. * **Package Firewall Policies**: These policies control install-time enforcement when developers install packages through the Package Firewall. You choose block, warn, or allow safe versions actions for malware and minimum package age, block or warn actions for restricted licenses and vulnerabilities, and you define exceptions for packages that should bypass checks. You can also send Slack notifications when the firewall blocks or warns on a package installation. Policies See [Policies](/platform-administration/policies) for more information. ## Notifications The Notifications page keeps you updated on security events and policy violations. It has three categories: * **Open**: Displays active notifications that require attention. * **Resolved**: Displays notifications that you already addressed. * **All**: Displays a complete history of all notifications. Users can set up notification integrations for **email**, **Jira**, **Slack**, **Vanta**, **webhooks**, **GitHub PR remediation**, and **GitHub PR comments**. Use filters to sort by time range and quickly find key details like timestamps, related policies, project names, evaluation times, violations, namespaces, and tags. Use the **Projects** filter to view notifications for specific projects, quickly narrowing your results. Notifications ## Integrations The **Integrations** page allows you to connect Endor Labs with external tools and services to enhance functionality and streamline workflows. You can set up integrations with security scanners, CI/CD pipelines, ticketing systems, and more. These integrations help automate security checks, improve vulnerability tracking, and ensure seamless communication between Endor Labs and other development tools. Integrations See [Endor Labs Integration](/integrations) for more information. ## Settings **Settings** enables users to configure platform preferences, security policies, and integrations. It includes: * **License**: This section provides details about the licensing information for Endor Labs products. Users can view current license status, contract, expiration date, features, and license consumption. * **System Settings**: These settings allow users to manage essential configurations such as Data Privacy, Endor Patches, Policies & Rules, and SBOM configurations. * **Saved Filters**: Users can create and manage reusable filters for findings and dependencies. They help users to apply custom views and criteria to their data. * **Scan Profiles**: This feature allows users to define and customize scanning configurations. A scan profile can include specific parameters, toolchains, and paths to different projects. * **Build Tools**: This allows users to set up integrations for dependency analysis ensuring that the software build process incorporates dependency checks. * **AI Access**: This section provides details about AI powered features in Endor Labs that enhance security analysis and code insights. It includes capabilities like LLM code processing and C/C++ embeddings. * **Access Control**: Configure workspace authentication and access management, including auth policies, API keys, SSO/identity providers, and user invitations. * **Namespaces**: Organize projects into namespaces and manage access controls across teams, including creating, editing, and deleting namespaces. Settings See [Platform administration](/platform-administration) for more information. ## Get started The Get started page helps you quickly familiarize yourself with Endor Labs and make the most of its features. It provides a step-by-step guide to setting up your first project and understanding key functionalities. Get Started See [Getting started](/introduction/getting-started) for more information. # Getting started Source: https://docs.endorlabs.com/introduction/getting-started/index Set up and configure Endor Labs to run your first project scan. This guide walks you through logging in, exploring the product, and running your first scan. See [Endor Labs user interface](/introduction/endor-labs-ui) for more information on the main elements of the interface. You need an Endor Labs account and a tenant to use Endor Labs. Visit [https://app.endorlabs.com](https://app.endorlabs.com) to access the login page. You can sign in with the following options: If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. * Google Workspace * GitHub * GitLab * Email Link * [Supported enterprise SSO providers](/platform-administration/rbac/authentication-providers/custom-identity-providers) Select **User menu** > **Get Started** from the left sidebar to open the **Getting Started Checklist**. * Click **Start Scan** under **Scan a project** to connect your Git provider and scan your repositories for vulnerabilities, license risks, and dependency issues. * Click **Go to Findings** under **View and filter findings** to review findings after your scan completes. * Enter email addresses under **Invite your team** to give colleagues direct access to your trial. * Click **Explore Demo Sandbox** to explore Endor Labs capabilities. Select **Explore Demo Sandbox** to view Endor Labs capabilities and explore its features in a read-only tenant. The sandbox lets you explore findings, policies, and dashboards before connecting your own repositories. You can start scanning your repositories using any of the following: **SCM integrations** * [GitHub Cloud App Pro](/setup-deployment/scm-integrations/github-app) * [GitLab App](/setup-deployment/scm-integrations/gitlab-app) * [Bitbucket Cloud](/setup-deployment/scm-integrations/bitbucket-cloud) * [Bitbucket Data Center](/setup-deployment/scm-integrations/bitbucket-datacenter-app) * [Azure App](/setup-deployment/scm-integrations/azure-app) **CLI** * [endorctl](/setup-deployment/cli/scan-using-endorctl) **CI/CD environments** * [GitHub Actions](/setup-deployment/ci-cd/scan-with-github-actions) * [GitLab CI](/setup-deployment/ci-cd/scan-with-gitlab) * [Azure DevOps](/setup-deployment/ci-cd/scan-with-azuredevops) * [Bitbucket Pipelines](/setup-deployment/ci-cd/scan-with-bitbucket) * [Jenkins](/setup-deployment/ci-cd/scan-with-jenkins) * [CircleCI](/setup-deployment/ci-cd/scan-with-circleci) * [Google Cloud Build](/setup-deployment/ci-cd/scan-with-google-cloud-build) * [Buildkite](/setup-deployment/ci-cd/scan-with-buildkite) To view and filter findings: 1. Select **Findings** from the left sidebar or click **Go to Findings** to view all findings. 2. Use the filters to refine your search and view findings by project, severity, or category. 3. Click a finding to view its details and take action. # Endor Labs licenses Source: https://docs.endorlabs.com/introduction/licenses/index Licensing model, SKUs, and per-seat entitlements for the Endor Labs platform. Endor Labs is licensed per contributor per year, with **Core** and **Pro** tiers across the **Open Source** and **Code** product lines. Each seat comes with a daily scan credit allocation that pools across your contract term, plus support for onboarding multiple repositories. License consumption is measured from the developers who commit to your monitored repositories. You can track consumption against your contracted count, along with scan credit usage and license details. See [license consumption](/platform-administration/license#license-consumption) to learn more. ## License tiers and SKUs All license tiers are priced **per Code Contributor per year**. A **Code Contributor** is any developer who has made one or more commits to a private source code repository monitored by Endor Labs in the last 90 days. The current SKU lineup and per-SKU feature lists are maintained on the [Endor Labs pricing page](https://www.endorlabs.com/pricing). That page is the authoritative source for Endor Labs SKUs and licenses. Each license is sold standalone and priced per Code Contributor per year. **Endor Open Source** and **Endor Code** licenses have scan credit allocations based on the license and the number of Code Contributors. If you exhaust your scan credits, you need to buy the add-on license **Endor Additional Code Scans** (`EL-ADD-SCANS`). This extends scan capacity beyond your per-seat scan credit pool. It is sold in buckets of 10,000 scans. ## Entitlements and limits This section describes how seats, scan credits, repository caps, and overage work across product licenses. The limits described in the following sections are **fair usage** limits, sized to the number of seats you purchase. The limits are generous and you will never be blocked from scanning. Teams running scan-intensive workflows can purchase additional scan credits if they need to, but most organizations won't need to. ### Per-seat scan credit allocation Daily allocations accumulate into a shared pool across your contract term. You can draw from this pool flexibly so that a high-volume PR day isn't blocked as long as the pool has remaining credits. When a Code Contributor is licensed for more than one tier, daily allocations stack. For example: * **OSS Core + Code Core** = 2 additional scans / Code Contributor / day * **OSS Pro + Code Pro** = 3 additional scans / Code Contributor / day (1.5 + 1.5) * **OSS Core + Code Pro** = 2.5 additional scans / Code Contributor / day ### Included and additional scans Each Code Contributor seat supports unlimited default branch scans (typically `main` or `master`) for up to 5 repositories. Beyond that, default branch scans are counted as additional scans. A non-default branch scan is any scan you trigger against a branch other than your default branch. For example: a feature, release, or hotfix branch. The following scans count against your credits: * Pull request scans * Non-default branch scans * MCP scans invoked without `--dry-run` * Default branch scans for repositories beyond the 5 × seats limit The following scans do not count against your credits: * Default branch scans within the 5 × seats repository limit * Local IDE scans (`--dry-run`) * SBOM uploads * Container scans (on-premises) * Binary or package scans ### Credit pooling Credits pool across the full duration of your contract: * **Annual billing**: Credits unlock yearly at each renewal anniversary. * **Prepaid multi-year contracts**: All credits across the full term are available upfront. For example: * 100 OSS Core seats × 1 year = **36,500 scan credits** for use during that contract year. * 100 OSS Pro seats × 1 year = **54,750 scan credits** for use during that contract year (Pro allocates 1.5 / seat / day). * 100 OSS Core seats × 3 years prepaid = **109,500 scan credits** available upfront across the full term. Pools provide flexibility within the contract. High-volume PR days are supported as long as the pool has credits remaining. ### Overage If your scan credit pool is exhausted, you can purchase additional scans in buckets of 10,000 scans as **Endor Additional Code Scans** (`EL-ADD-SCANS`). The platform continues to function without interruption if you exceed your allocation. Overage is handled through your account team. # AI security code review Source: https://docs.endorlabs.com/inventory-insights/dashboards/ai-security-review/index Visualize the AI security review results in your organization. The AI security code review dashboard helps you understand the impact of AI security code review in your namespace. AI security code review dashboard You can view the following information in the AI security code review dashboard: * **PRs without summaries**: The percentage of pull requests that did not have a summary for which AI security code review generated meaningful summaries. * **Safe Pull Requests**: The percentage of pull requests that did not have any High or Critical vulnerabilities. * **Review time saved**: The estimated number of hours of developer time saved by AI security code review. * **Projects enabled**: The number of projects in the namespace that have AI security code review enabled. * **Pull requests reviewed**: The number of pull requests reviewed by AI security code review. * **Commits reviewed**: The number of commits reviewed by AI security code review. * **Security findings**: The number of security findings triggered by AI security code review, classified by severity. You can also view the following widgets: * **Top categories by findings**: The categories of security vulnerabilities found in the namespace, ranked by the number of findings. * **Top projects by findings**: The projects in the namespace with the highest number of security vulnerabilities, ranked by the number of findings. * **Top languages by findings**: The languages in the namespace with the highest number of security vulnerabilities, ranked by the number of findings. You can use these widgets to identify the most critical vulnerabilities and projects in your namespace. # Analytics Source: https://docs.endorlabs.com/inventory-insights/dashboards/analytics/index Visualize metrics on volume and efficiency of issue resolution. Analytics dashboard offers a comprehensive view of your security metrics, and tracks finding trends and resolution times across projects. Use it to quickly assess risk levels, monitor progress, and identify areas needing improvement in your security posture. ## Set the filters Customize the data displayed on the Analytics dashboard by applying specific filters to focus on the most relevant information, enabling better analysis and decision-making. Adjusting the filters ensures that you can track progress and identify trends that are critical to your security and development goals. These are global filters and apply to all widgets on this dashboard. * **Severity**: Filter the data based on finding severity such as Critical, High, Medium, or Low (labeled C, H, M, and L in the user interface). * **Category**: Filter the findings by category such as AI models, vulnerability, SCA, SAST, secrets, and container. * **Attributes**: Narrow down the list based on a range of factors such as: * if a patch is available to fix the findings * if the vulnerable function is reachable * if the dependency is reachable * if the dependency originates from a current repository or a current tenant * if the dependency is a test dependency * if the dependency's discovery type is manifest, phantom, or segment match * if the finding originates from itself, direct, or a transitive dependency * filter the findings by the **Exploited** tag from **CISA KEV** * filter the findings by the **Warn** or **Break the Build** options set in the [action policy](/platform-administration/policies/action-policies#create-an-action-policy-from-template) See [Finding attributes](/inventory-insights/findings#finding-attributes) for more information. * **When was the Finding first introduced** - Select a date range from the available options to filter the analytics data based on when the finding was first scanned. By default, the dashboard shows data from the last 90 days. ## Findings snapshot metrics Get a quick overview of key metrics for the selected category, helping you monitor newly identified and resolved findings, as well as the time it takes to address them. Here's what each metric represents: * **Newly Discovered**: The number of findings recently identified across your projects. This count indicates areas that may need attention or remediation. * **Resolved**: The number of findings fixed or mitigated recently, reflecting progress in securing your projects. * **Mean Time to Resolve**: The average time, in days, it takes to resolve a finding once discovered. Lowering this number can indicate faster responses to security issues. * **Minimum Time to Resolve**: The shortest time it took to resolve a finding in the current tracking period, providing insight into how quickly you can address issues. * **Maximum Time to Resolve**: The longest time it took to resolve a finding, showing the upper range for resolution times and highlighting areas where responses might need improvement. These metrics help track security effectiveness over time and identify trends in finding resolution within your projects. ## Analytics for AI models, SCA, SAST, secrets, and container When you select **AI models**, **SCA**, **SAST**, **secrets**, or **container** as the category filter, the dashboard displays the following sections. Analytics for SCA findings ### Findings over time The **Findings over Time** chart tracks the number of newly discovered and resolved findings across your projects over the [selected period](#set-the-filters). This view helps you analyze trends in finding discovery and resolution, showing whether security issues are increasing, decreasing, or remaining steady over time. ### Time for issues resolved The **Time for Issues Resolved** chart displays the number of days taken to resolve issues over the selected period. This metric helps assess response efficiency, highlighting how quickly you address security and other issues, and can indicate improvements or delays in issue resolution processes. ### New open findings approaching SLA The **New Open Findings Approaching SLA** section shows findings that are close to missing their resolution deadlines, with less than 24 hours remaining. This allows you to prioritize issues and take immediate action to resolve them before you miss the SLA. To define or adjust SLA durations, see [Set SLA for findings](#set-sla-for-findings). ## Analytics for vulnerabilities When you select **Vulnerability** as the category filter, the dashboard displays all the charts and metrics described above, plus additional dependency trend charts specific to vulnerability analysis. Analytics charts for vulnerabilities ### Vulnerabilities over time The **Vulnerabilities over Time** chart tracks the number of detected vulnerabilities across your projects over the [selected period](#set-the-filters). This view helps you analyze trends in vulnerability discovery and resolution, showing whether security issues are increasing, decreasing, or remaining steady over time. ### Time for vulnerabilities issues resolved This chart displays the number of days taken to resolve vulnerability issues over the selected period. This metric helps assess response efficiency, highlighting how quickly you address vulnerabilities, and can indicate improvements or delays in issue resolution processes. ### New open vulnerabilities approaching SLA The **New Open Vulnerabilities Approaching SLA** section shows vulnerabilities that are close to missing their resolution deadlines, with less than 24 hours remaining. This allows you to prioritize issues and take immediate action to resolve them before you miss the SLA. To define or adjust SLA for different vulnerability severities, see [Set SLA for findings](#set-sla-for-findings). ### Outdated dependencies trend This chart tracks the number of outdated dependencies in your projects over time. It helps you monitor the progress of updating libraries and frameworks, providing insights into how many dependencies are no longer up-to-date. By identifying trends, you can prioritize updating critical dependencies, reduce security risks, and ensure your projects remain current with the latest versions. A dependency qualifies as outdated if it is older than 10 months and at least 5 releases behind the latest release. ### Unmaintained dependencies trend This chart shows the number of dependencies in your projects that are no longer actively maintained over time. This helps you track the accumulation of unsupported libraries and frameworks, which may pose security and compatibility risks. By monitoring this trend, you can take proactive steps to replace or update unmaintained dependencies, ensuring the stability and security of your projects. ### Unused dependencies trend This chart tracks the number of dependencies in your projects that are no longer in use over time. This helps identify redundant libraries or packages that can be safely removed, reducing the overall project size and improving performance. By monitoring this trend, you can streamline your codebase and reduce potential security risks from unnecessary dependencies. ## Create an analytics report Generate an analytics report from the dashboard to export the metrics and trends shown for your current filter selection. 1. Select **Home** > **Analytics** from the left sidebar. 2. Apply the filters you want to include in the report. 3. Click **Create Report**. 4. Choose a report type, output format, scope, and any additional filters. 5. Click **Create Report**. See [Reports](/inventory-insights/reports#create-a-report) for more information about report types, formats, and management. ## Set SLA for findings A Service Level Agreement (SLA) defines the expected time frame within which you should address security findings, based on their severity. It sets a deadline for resolving new open findings before they approach or breach SLA. Follow these steps to define SLA for findings: 1. Select **Home** > **Analytics** from the left sidebar. 2. Scroll down to **New Open Findings Approaching SLA** and select a severity level to set the SLA for it. The default SLA for severities are: * Critical - 30 Days * High - 30 Days * Medium - 90 Days * Low - 180 Days. For example, click **SLA** duration for Critical to modify it. 3. In **SLA DURATION**, set a duration in days for the selected severity level. 4. Click **Reset** to restore the SLA to its default duration. 5. Click **Save**. # Endor Patches Source: https://docs.endorlabs.com/inventory-insights/dashboards/endor-patches/index Explore the benefits of Endor Patches on the dependencies identified within your organization. Endor Patches dashboard provides you with metrics to understand the impact of using Endor Patches and remediating vulnerabilities. ## Set the filters Customize the data displayed on the dashboard by applying specific filters to focus on the most relevant information, enabling better analysis and decision-making. **critical(C)** or **high(H)** priority findings: Customize the displayed data by selecting critical or high priority findings or both. **Reachability**: Filter the data by reachable function or reachable dependency. * Select **Yes** to include reachable function or dependency. * Select **No** to exclude reachable function or dependency. * Select **Potential** to include potentially reachable functions or dependencies. These are global filters and apply to all widgets on this dashboard. ## Use impact calculator Use the impact calculator to see the number of critical and high findings remediated after applying the recommended Endor Patches. Impact Calculator ## View impact of Endor Patches The Top Impact by Endor Patches section shows available patches you can request, along with a list of dependencies, their current versions, findings, and impacted projects and package versions. You can expand a dependency to view detailed information and click **Export All as CSV** to download the data for offline analysis. ### View available Endor Patches To view Endor Patches that are available and ready for use: 1. Select the **Available** preset filter to show Endor Patches that are already available. 2. You can review dependencies, fixable findings, and affected projects and package versions to understand the impact of a patch. Available endor patches 3. Select a dependency row to view details about the dependency. * Select **Overview** to review key metrics, patch attestations, and a detailed fixable findings list with severity, advisories, and CVEs. * Select **Patches** to view total commits and all the file-level changes. Available patch details ### Request Endor Patches 1. Select the **To Request** preset filter to show dependencies where you can ask Endor Labs for a patch. 2. Select **Request Now** to start a new request. Enter a comment and select **Send Request**. Endor patches to request 3. Select a dependency row to view details such as request status, fixable findings, projects impacted, and package versions impacted. Request patches details #### Patch request lifecycle The patch request lifecycle consists of four stages: Open, In Process, Done, and Won't Do, each representing a different phase of assessment and development. * **Open**: Endor Labs is assessing the request's feasibility. * **In Process**: Endor Labs is actively developing the patch for the request. * **Done**: The patch is now available. * **Won't Do**: Endor Labs has determined that the request is not feasible. # First-party code Source: https://docs.endorlabs.com/inventory-insights/dashboards/first-party-code/index Visualize the first-party code vulnerabilities in your organization. Use the widgets in the first-party code dashboard to understand the vulnerabilities in your codebase from a SAST and secrets perspective. Dashboard represents the vulnerabilities across all the projects in the given namespace. First-party code dashboard The following sections describe the widgets in the first-party code dashboard and how to use them. * [Set the filters for the dashboard](#set-the-filters-for-the-dashboard) * [SAST findings](#sast-findings) * [Secrets findings](#secrets-findings) * [OWASP Top 10 by severity](#owasp-top-10-by-severity) * [Top 10 secret rules by severity](#top-10-secret-rules-by-severity) * [Top Projects by SAST findings](#top-projects-by-sast-findings) * [Top Projects by secrets findings](#top-projects-by-secrets-findings) ### Set the filters for the dashboard You can filter the data displayed on the dashboard by applying filters based on the severity of the findings. You can choose the combination of critical, high, medium, and low severity findings. ### SAST findings Displays the number of open SAST findings categorized by severity and languages. Click on the severity or language to view the list of specific findings. ### Secrets findings Displays the number of open secrets findings. Valid secrets are critical in nature while invalid secrets are informational in nature with a low severity. The secrets finding policy configured for the projects determines these findings. Click on the type of secret to view the list of specific findings. ### OWASP Top 10 by severity Displays the number of OWASP Top 10 findings across your projects in a stacked bar chart. Each bar chart represents the OWASP security risk categorized by severity. Click on the bar to view the list of the SAST findings for that risk. ### Top 10 secret rules by severity Displays the number of top 10 secret detection rule findings across your projects in a stacked bar chart. Each bar represents a secret rule categorized by severity. Click on a bar to view the list of findings identified by that secret rule. ### Top Projects by SAST findings Lists the top five projects with the highest number of SAST findings. Click on the project to view the list of SAST findings associated with the project. ### Top Projects by secrets findings Lists the top five projects with the highest number of secrets findings. Click on the project to view the list of findings associated with the project. # Dashboards Source: https://docs.endorlabs.com/inventory-insights/dashboards/index View analytics, security posture, and vulnerability insights. Dashboards offer a concise and visual way to monitor the security posture of the projects in your organization. They are interactive and help you visualize how you use your projects, packages, and dependencies. Dashboards provide the following capabilities to monitor potential threats: * Gain real-time insights across your code inventory through a range of system widgets that display information in the form of bar graphs. * Aggregate and analyze findings, vulnerabilities, and dependencies using visual metrics for a clearer understanding. * Monitor most used or least used dependencies through real-time visibility and updates. * Understand how Endor Patches can help you remediate your findings. * Track security metrics, vulnerability trends, and resolution times across projects. * Visualize the vulnerabilities in your codebase from a SAST and secrets perspective. Endor Labs comes with multiple out-of-the-box widgets to enable teams to understand potential risks and take preventive measures. Widgets in the Endor Labs dashboards consolidate related data of a single type, providing valuable information. Visualize consolidated information on OSS vulnerabilities Visualize impact of applying Endor Patches for your repositories Visualize the first-party code vulnerabilities in your organization Visualize real-time insights into key performance indicators and metrics Visualize the AI security code review results in your organization Visualize reachability analysis coverage across your organization # OSS Coverage Source: https://docs.endorlabs.com/inventory-insights/dashboards/oss-coverage/index Beta
Visualize dependency resolution and reachability analysis coverage across your organization. Use the OSS Coverage dashboard to understand how successfully Endor Labs resolved dependencies and performed reachability analysis for your scanned projects. Use it to identify gaps in scan quality and take action to improve coverage. OSS Coverage dashboard ## Set the filters Customize the data displayed on the OSS Coverage dashboard by applying filters to focus on the most relevant projects and ecosystems. These are global filters and apply to all widgets on this dashboard. * **Projects**: Filter coverage metrics to one or more specific projects. * **Project Tags**: Filter by tags applied to your projects. * **Ecosystems**: Filter by package ecosystem, for example, Maven, npm, or PyPI. ## Dependency Resolution Coverage The **Dependency Resolution Coverage** widget shows the percentage of scanned projects for which Endor Labs successfully resolved the full dependency graph. Dependency resolution is a prerequisite for accurate vulnerability detection. Projects where resolution fails may have incomplete findings. The widget displays the following categories: * **Successful**: Projects where dependency resolution completed without errors. * **Successful After Fixes**: Projects where dependency resolution succeeded after automated remediation steps were applied. * **Not Successful**: Projects where dependency resolution failed. These projects are candidates for investigation. See [Add private registry integration](#add-private-registry-integration) for common causes and fixes. The percentage in the center of the chart reflects combined coverage including projects that succeeded after fixes. ## Reachability Coverage The **Reachability Coverage** widget shows the percentage of scanned projects for which Endor Labs was able to perform reachability analysis — determining which vulnerabilities in your dependencies are actually reachable from your application code. Higher reachability coverage means Endor Labs can more accurately prioritize exploitable vulnerabilities, reducing false positives. The widget displays the following categories: * **Successful**: Projects where full reachability analysis was completed using a first-party analysis of your code. * **Successful with Pre-Computed**: Projects where reachability was determined using pre-computed call graph data from the Endor Labs database, rather than a direct analysis of your code. * **Successful After Fixes**: Projects where reachability analysis succeeded after automated fixes were applied. * **Not Successful**: Projects where reachability analysis could not be completed. The percentage in the center of the chart reflects total coverage across all successful categories, including pre-computed and post-fix successes. ## Coverage error buckets When dependency resolution or reachability analysis is not fully successful, the dashboard groups the underlying errors into three expandable buckets. Each bucket includes an **Error Description** table listing the specific errors encountered, along with the number of **Projects** and **Packages** affected. Click any row to open a detail drawer with the full scan log for that error. Coverage error buckets ### Add private registry integration The **Add private registry integration** bucket lists errors caused by dependencies that Endor Labs could not locate in a public registry. This typically occurs when a project depends on packages hosted in a private npm, Maven, PyPI, or Docker registry that Endor Labs does not yet have access to. Example error: **Package not found in PyPI** — Check if you have configured a private package registry for PyPI, otherwise this dependency may not exist. To resolve these errors, connect your private registry so that Endor Labs can authenticate and fetch internal packages during scanning. ### Customize your tenant's build tools The **Customize your tenant's build tools** bucket lists errors caused by build environment mismatches — for example, an incompatible language version, missing build tool, or dependency conflict that prevents Endor Labs from resolving the project's dependency graph. These errors typically occur when a project requires a specific runtime or toolchain configuration that differs from the Endor Labs default scanning environment. To resolve these errors, configure language versions, tools, and dependencies to match your project's requirements. Click **Customize your toolchains** in the dashboard to update your tenant's build tool settings, or see [Build tools](/best-practices/build-tools-use-case). ### Other Errors The **Other Errors** bucket lists errors that are not addressable through registry configuration or toolchain customization. These typically occur when a project requires a self-hosted CI environment, targets Windows-specific dependencies, relies on proprietary tooling, or uses specialized system configurations that are not supported in the Endor Labs scanning environment. These errors may require changes to how the project is scanned, such as running `endorctl` directly in your own CI pipeline where the required environment is available. See [CI/CD Integration](/setup-deployment/ci-cd) for more information. ## View the full scan log Each row in the error tables links to a detail drawer that shows the full scan log for that error. You can view details such as: * The affected project name and branch. * A link to the project repository. * The full error log output from the scan, showing the exact failure message returned during dependency resolution. * **View Full Log**: Opens the complete, untruncated scan log for deeper investigation. * **Go to Scan History**: Opens the scan history page for the affected project so you can review previous scan runs and track when the error was first introduced. Coverage scan log # OSS overview Source: https://docs.endorlabs.com/inventory-insights/dashboards/oss-overview/index Visualize complete software security posture of your organization. Use the widgets in OSS overview dashboard to understand your codebase, dependencies, vulnerabilities, and overall software security posture. ## Scanned by Endor Labs Displays information on the following scan statistics across all ecosystems in the given tenant: * Total number of dependencies, categorized into direct and transitive dependencies * Total number of vulnerabilities, categorized into unreachable and other vulnerabilities * Total number of projects * total number of packages * Total number of scans * Total number of configured notifications ## Vulnerability prioritization funnel Endor Labs' vulnerability prioritization funnel systematically assesses and categorizes vulnerabilities based on their severity and category. Endor Labs prioritizes vulnerabilities in the following order: * **Total open vulnerabilities**: Indicates the complete list of vulnerabilities detected in all the scanned projects in this tenant. * **Not in test**: Indicates the list of vulnerabilities that are present in the production code and not in the test code. * **Fix available**: Indicates the list of vulnerabilities in the production code, for which a fix is available. * **Reachable**: Indicates the list of vulnerabilities in production code, with a fix, that attackers can access or exploit. Customize the reachable findings for your organization. You choose to see the data for reachable functions or potentially reachable functions, or for both. See [Customize finding reachability](#customize-finding-reachability). * **Exploitable likelihood**: Indicates the list of vulnerabilities in production code, with a fix, that are reachable, and with an EPSS probability score greater than 1%. Click **Low Risk Upgrades** in the vulnerability prioritization funnel to view findings with low remediation risk, if present in your namespace. Use the search bar to filter projects by name and view their OSS overview. The search supports partial matching. For example, when you search `repo`, the system displays all projects containing `repo` in their title along with their corresponding OSS overview data. Vulnerability funnel You require an Endor Labs OSS Pro license to access the **Low Risk Upgrade** feature. By applying this funnel approach, organizations can prioritize addressing the most critical, exploitable, and actionable vulnerabilities first, maximizing their security efforts. ### Customize finding reachability Customize finding reachability for your organization. The data in the **Vulnerability Prioritization Funnel** 1. Select **Home** > **OSS overview** from the left sidebar. 2. Navigate to the **Vulnerability Prioritization Funnel** and click the vertical three dots. 3. In **FINDING REACHABILITY**, define your finding reachability criteria. You can select **Reachable Function**, **Potentially Reachable Function**, both options, or neither. 4. Click **Save**. 5. Click **Reset** to restore finding reachability to your last set values. Vulnerability funnel customization ### Development hours and cost saved Visualize the hours and cost saved metrics information on the dashboard. * **Dev Hours Saved** - Development hours saved estimates the time saved by reducing the number of vulnerabilities that developers must prioritize. See [Customize development hours](#customize-baseline-for-development-hours). * **Cost Saved** - Cost savings estimates the value by multiplying the saved developer hours with the full-time equivalent (FTE) hourly cost for triaging vulnerabilities. See [Customize cost baseline](#customize-baseline-for-cost). #### Customize baseline for development hours Adjust the development baseline to meet your organization's specific needs. 1. Select **Home** > **OSS overview** from the left sidebar. 2. Navigate to the **Dev Hours Saved** and click the vertical three dots. 3. Choose **BASELINE** and set **DEV HOURS** for a record on the **Vulnerability Prioritization Funnel**, * **Total Open Vulnerabilities**: Provide approximate development hours required to triage all open vulnerabilities. By default, the dashboard calculates development hours saved from this baseline and displays them on the **Vulnerability Prioritization Funnel**. * **Not In Test**: Provide approximate development hours required to triage vulnerabilities in production code. * **Reachable**: Provide approximate development hours required to triage accessible and most exploitable vulnerabilities. * **Fix Available**: Provide approximate development hours required to triage vulnerabilities you can fix with a patch or an upgrade. 4. Click **Save**. #### Customize baseline for cost Tailor the cost baseline to reflect the Full-Time Equivalent cost of your organization. 1. Select **Home** > **OSS overview** from the left sidebar. 2. Navigate to **Cost Saved** and click the vertical three dots. 3. Enter an **HOURLY COST** and **CURRENCY** that applies to one full-time employee following your organization's application security program. 4. Click **Save**. ## Top projects metrics View the top project data by all findings, all vulnerabilities, reachable vulnerabilities, outdated dependencies, and unmaintained dependencies. You can identify the numbers for critical, high, medium, and low risk severity findings. Click the bar graph to view complete details. ## Top packages metrics View package data by all findings, all vulnerabilities, reachable vulnerabilities, outdated dependencies, and unmaintained dependencies. You can identify the numbers for critical, high, medium, and low risk severity findings. Click the bar graph to view complete details. # Working with dependency filters Source: https://docs.endorlabs.com/inventory-insights/dependencies/dependency-filters/index Learn how to implement and use dependency filters to search, prioritize, and manage dependencies across your organization. Filters enable targeted queries on dependencies based on attributes such as ecosystem, reachability, direct versus transitive usage, discovery type, approximate resolution, severity, and Endor scores. This guide explains how dependency filters work, how to apply and combine them effectively, and provides practical examples to support triage, audit, and reporting workflows across your dependency inventory. ## How filters work Each filter consists of three parts. * **Key**: The attribute you want to filter (for example, `Ecosystems`, `Dependency Reachability`, and `Direct`). * **Operator**: The comparison logic (for example, `equals`, `in`, and `greater than` ). * **Value**: The target value to evaluate (for example, `Maven` and `Yes`). Dependency filters use standard comparison operators to evaluate criteria. See [Filter operators](/developers-api/rest-api/using-the-rest-api/filters#operators) for detailed information about available operators and their usage when using the API. When you apply multiple filters, the system combines them using logical AND operations across filters for different fields and logical OR operations across filters for the same field. For example: * **Filter 1**: `Ecosystems in: npm` * **Filter 2**: `Dependency Reachability: Potentially Reachable` * **Filter 3**: `Direct: Yes` * **Filter 4**: `Dependency Scopes: Normal` Multiple dependency filters applied This combination returns only dependencies that are in the npm ecosystem, potentially reachable in your code, direct, and have normal scope. ## Filter implementation techniques You can use the following filter types to manage your dependencies effectively. * [Preset filters](#preset-filters): Use the filter bar in the Endor Labs user interface to quickly segment dependencies by common attributes. * [Filter dependencies using API](#filter-dependencies-using-api): Use the REST API or endorctl for complex queries and logical combinations. ### Preset filters The following examples demonstrate how to apply preset filters for common dependency scenarios. #### Filter dependencies by project Use the **Projects** filter to show only dependencies used by one or more selected projects. You can search by project name or tags, and click **Add Filter**. For example, to view only dependencies used by a specific application, search by project name or tags Filter by project #### Filter dependencies by ecosystem Use the **Ecosystems** filter to segment dependencies by package manager or language for targeted security policies, license compliance, or ecosystem-specific upgrade campaigns. For example, to focus on Maven dependencies for a Java security assessment, use the `Ecosystems in: Maven` filter. Filter by ecosystem #### Filter dependencies by reachability Use the **Dependency Reachability** filter to focus on dependencies that are reachable from your application code. Reachable dependencies are the ones that execute at runtime and increase your exposure to vulnerabilities. You can filter by **Reachable**, **Potentially Reachable**, or **Unreachable** dependency. For example, to prioritize remediation of dependencies your application might call at runtime, use the `Dependency Reachability: Potentially Reachable` filter. Filter by dependency reachability #### Filter dependencies by scope Use the **Dependency Scopes** filter to separate production dependencies from those used only for testing or build-time tasks, so that you can target the right ones for policies and reports. You can filter by: * **Normal**: Production dependencies consumed by the application at run time. * **Test**: Dependencies used only in test scope, such as test frameworks and test-only libraries. * **Build**: Dependencies used only at build or development time, such as compilers, build tools, or dev-only tools. For example, to show only production dependencies, use the `Dependency Scopes: Normal` filter. Filter by dependency scope #### Filter dependencies by declaration Use the **Direct** filter to distinguish between dependencies you declare explicitly in your manifests and those pulled in transitively. For example, to view only direct dependencies, use the `Direct: Yes` filter. Filter by direct #### Filter dependencies by public Use the **Public** filter to show dependencies from public registries (npm, Maven Central, PyPI) or from private sources. For example, to view only dependencies from public package sources, use the `Public: Yes` filter. Filter by public #### Filter dependencies by vendored Use the **Vendored** filter to scope results by whether your repository embeds dependency artifacts, such as version-controlled source or shaded JARs, rather than resolving them from a package registry. The **Vendored** filter applies only to dependencies used by [Endor Patches](/risk-remediation/endor-patches). It does not affect regular OSS dependency ingestion. For example, to narrow your Endor Patches dependency review to only non-vendored dependencies, use the `Vendored: No` filter. Filter by vendored #### Filter dependencies by approximation Use the **Approximation** filter to distinguish dependencies inferred during fallback dependency resolution from dependencies fully resolved from manifests and lockfiles. Approximate dependencies can still appear in findings, but they may be less accurate than fully resolved dependencies. For example, to review only dependencies discovered through approximate resolution, use the `Approximation: Yes` filter. See [Approximate scans](/scan/sca/approximate-scans) for more information on approximate resolution. Filter by approximation #### Filter dependencies by discovery type Use the **Discovery Type** filter to restrict results by how the dependency was found. You can filter by **Manifest** (declared in a manifest), **Phantom** (phantom or imported dependency analysis), or **Segment match** (code segment match). For example, to focus on phantom dependencies, use the `Discovery Type: Phantom` filter. Filter by discovery type #### Filter dependencies by pinned Use the **Pinned** filter to tell whether the dependency version is pinned to a specific version or range. Unpinned direct dependencies are a common operational and supply chain risk because builds can pull different versions over time. For example, to list only pinned dependencies, use the `Pinned: Yes` filter. Filter by pinned #### Filter dependencies by scan timestamp Use the **Last Scanned** filter to identify dependencies with stale security data that require fresh scans for current security posture. You can select from predefined time ranges or use the calendar to select a specific date. For example, to identify dependencies scanned within the last 24 hours, use the `Last Scanned: Last Day` filter. Filter by last scanned #### Filter dependencies by release date Use the **Released** filter to focus on recently released dependency versions for upgrade planning or to track new releases. You can select from predefined time ranges or use the calendar to select a specific date. For example, to find dependencies released in the last week, use the `Released: Last Week` filter. Filter by release date ### Filter dependencies using API For complex queries, use the advanced filter syntax to combine multiple attributes and apply logical operators. Use the [Dependency filter builder](#interactive-filter-builder) to assemble conditions interactively. The following table lists the available attributes for dependency filters. #### Interactive filter builder #### API filter use cases The following examples demonstrate how to combine these attributes for common security and compliance workflows. List only direct dependencies for a given project. ```bash theme={null} spec.importer_data.project_uuid== and spec.dependency_data.direct==true ``` Focus on direct dependencies of a root package version that are also reachable, for prioritization. ```bash theme={null} spec.importer_data.package_version_uuid== and spec.dependency_data.direct==true and spec.dependency_data.reachable==REACHABILITY_TYPE_REACHABLE ``` Find dependencies that are end-of-life across the namespace for upgrade or replacement planning. ```bash theme={null} spec.dependency_data.eol==true ``` Limit to npm dependencies that are reachable from application code, across the namespace. ```bash theme={null} spec.dependency_data.ecosystem==ECOSYSTEM_NPM and spec.dependency_data.reachable==REACHABILITY_TYPE_REACHABLE ``` Find all public and non-vendored dependencies across the namespace for license or supply chain review. ```bash theme={null} spec.dependency_data.vendored==false and spec.dependency_data.public==true ``` Query across the namespace for dependencies that have a patch, without scoping by project. ```bash theme={null} spec.dependency_data.patched==true ``` # Dependencies Source: https://docs.endorlabs.com/inventory-insights/dependencies/index Explore the third-party packages your projects consume, with reachability, Endor Scores, and risk context. Dependencies are the third-party packages your projects pull in to deliver functionality. Endor Labs inventories every dependency it discovers across your tenant, scores each one, and tracks whether your code actually reaches it. Use the Dependencies page to assess supply chain risk, prioritize remediation, and understand how a dependency entered your environment. Select **Inventory** > **Dependencies** from the left sidebar to view every dependency in your namespace and its child namespaces, along with Endor Scores and malware status. Dependencies list view ## Direct and transitive dependencies Endor Labs classifies each dependency by how it enters your project. * **Direct dependencies**: Packages a developer explicitly declares in a manifest, such as `pom.xml` or `package.json`. * **Transitive dependencies**: Packages that enter the project indirectly through a direct dependency. Most projects have far more transitive than direct dependencies, and most supply chain vulnerabilities live in the transitive set. The **Is Direct** on the dependency list shows the type of dependency. ## Reachability states Reachability tells you whether your code actually exercises a dependency. Endor Labs uses static analysis and call graph generation to assign one of three states. * **Reachable**: Endor Labs traced a call path from your code to a function in the dependency. Findings on reachable dependencies are the highest priority for remediation. * **Unreachable**: Endor Labs found no call path from your code to the dependency. Findings here are typically lower priority. * **Potentially reachable**: Call graph analysis isn't available for the dependency's language or package manager, or analysis failed. Endor Labs can't confirm reachability either way. See [reachability analysis](/scan/sca/reachability-analysis) to learn how Endor Labs computes these states for each supported language. ## Endor Scores Endor Labs assigns four scores to each open source dependency so you can judge supply chain risk at a glance. * **Quality**: Reflects code health signals such as documentation, testing, and maintenance practices. * **Activity**: Reflects how actively the project is maintained, including release cadence and contributor activity. * **Security**: Reflects the dependency's vulnerability history and security posture. * **Popularity**: Reflects adoption signals such as downloads, stars, and dependent counts. Each score is the average of its underlying signals. Click any score in the sidebar or detail view to open the scorecard for that score and inspect the contributing signals. See [Endor scores](/scan/sca/scores) to learn the full methodology and signal definitions. ## Dependency metadata Each dependency carries metadata that helps you judge risk and plan upgrades. * **Type**: Direct or transitive, also shown as **Is Direct** in the list. * **Visibility**: Public when the dependency is publicly available, private when it comes from a private package. * **Source Available**: Whether the dependency's source code is auditable and linked to the package metadata. Endor Labs doesn't generate a scorecard when source isn't available. * **Dependent Packages**: The number of packages in the same project that rely on the dependency. * **Dependency Paths**: How a version enters a package. Use this to gauge the effort to upgrade a dependency and how deeply embedded it is in your ecosystem. * **Dependency Specification**: The import metadata captured for a direct dependency, such as whether it's scoped to tests only. The dependency list shows the core fields. Open a dependency to see the full set in the sidebar and detail view. ## Search and filter dependencies Filter dependencies to search, prioritize, and manage dependencies across your organization. You can filter dependencies by providing a filter criteria in the following way: 1. Select **Inventory** > **Dependencies** from the left sidebar. 2. Filter your dependencies using the list of available filters in the filter bar. 3. Toggle the **Advanced** option in the filter bar to apply API-style filters. Filter for reachable Maven dependencies You can combine multiple filters to create more specific searches and narrow down the dependency list based on multiple criteria. You can also use **Search Suggestions** to apply common queries with one click. These suggestions help you quickly segment the list for triage, upgrade planning, or ecosystem-specific reviews. See [Dependency filters](/inventory-insights/dependencies/dependency-filters) to learn how to implement these filters effectively. ## View dependency details Select a row in the dependency list to open the details on the right sidebar. The sidebar summarizes the dependency's metadata, findings, and Endor Scores. To open the full detail view directly, click the dependency's version name in the list. Dependency details sidebar Select **OSS Scores** in the sidebar to see the scorecard for the dependency. The scorecard lists every signal that contributed to each Endor Score. Scorecard panel listing the signals behind each Endor Score Click **View Details** in the sidebar to open the full detail view for the selected version. Full dependency version detail view The full detail view includes the following tabs: * **Overview**: Summary metadata for the dependency version. Overview tab with dependency version metadata * **Findings**: Security findings on the dependency. Select **Dependencies** inside **Findings** to see findings inherited from transitive dependencies. Findings inherited from related dependencies * **Dependents**: Projects in your tenant that use this dependency version, with the repository each project belongs to. Use this tab to identify affected projects when a vulnerability surfaces or when planning an upgrade across the tenant. Dependents tab listing projects that use this dependency version * **Dependencies**: Other dependencies this version brings in transitively. Dependencies tab listing transitive dependencies Click **Global View** to see every version of the dependency across your tenant. Global view across versions of a dependency Use the version dropdown to switch versions inside the detail view. Version selector dropdown in the detail view ## View dependency graph Select **Dependency Graph** in the full detail view to see how the dependency reaches your code. Use the search bar to locate a specific node in the graph. Dependency graph view Filter the graph with these controls: * **Severity filter**: Show only dependencies with findings at the chosen severity, such as Critical, High, Medium, or Low. * **Ecosystem**: Show only dependencies from one ecosystem, such as Maven, npm, PyPI, Go, or NuGet. * **Hide Unreachable**: Hide dependencies that aren't reachable from your code. * **Hide Without Findings**: Hide dependencies that have no security findings. ## Export dependencies Export filtered dependency lists to a CSV file for offline analysis. 1. Select **Inventory** > **Dependencies** from the left sidebar. 2. Enter search criteria or click **Add Filter** to narrow the list. 3. Click **Export Dependencies** and choose the columns to include: * UUID of the project * Ecosystem, such as Maven, npm, PyPI, Go, or NuGet * Name of the dependency * Version of the dependency * Tags associated with the dependency * Reachability of the dependency * **Is Direct**: Whether the dependency is direct or transitive * License information, including file, name, type, URL, and license text * Endor Scores: Quality, Activity, Security, and Popularity * Package version name (fully qualified name of the root package version) * Package version UUID * Project name (qualified package name of the root package) * Project UUID * **Endor Patch**: Whether an Endor Patch is available for the dependency Export dependencies column picker # Dismiss findings Source: https://docs.endorlabs.com/inventory-insights/findings/dismiss-findings/index Exclude findings from your active workflow using exception policies, ignore files, or snooze. Dismiss findings to exclude them from the active workflow. Dismissed findings no longer appear in active views and do not trigger policies. You can dismiss findings in one of the following ways: * [**Exception Policy**](#dismiss-findings-using-an-exception-policy): Applies during scan execution and suppresses all findings that match the defined criteria across the selected repository versions or projects. * [**Snooze**](#snooze-findings): Applies to a single finding instance for a specific target, repository version, and project. It takes effect immediately and applies only to the selected finding instance. You can't snooze pull request findings, as each pull request represents a new repository version. However, you can dismiss PR findings using [incremental PR scans](/scan/pr-scans#perform-incremental-pr-scan), [Exception Policy](/platform-administration/policies/exception-policies#create-an-exception-policy-from-a-template), or [ignore files](#dismiss-findings-using-an-ignore-file). * [**Ignore File**](#dismiss-findings-using-an-ignore-file): Applies during scan execution and suppresses all findings matching the ignore file entries. Ignore files are part of the source code and are only applied to the parent repository version. ## Dismiss findings using an exception policy Add an exception policy to prevent a finding from triggering action policies in future scans. 1. Select **Projects** from the left sidebar. 2. Search for and select a project, and select **Findings**. 3. Search for findings using advanced or basic filters. 4. Select findings and click the vertical three dots. 5. Select **Add Exception**. Exception from finding Use the **Grouped By** filter to group multiple findings and apply exceptions to them at once. See [Create exception policy](/platform-administration/policies/exception-policies) for details on how to create and apply exceptions. ## Snooze findings Snooze a finding to temporarily dismiss it and choose when it should reappear for findings that do not require immediate action or a permanent exception policy. To dismiss multiple findings, or a single finding across multiple repository versions or projects, create an [exception policy](/platform-administration/policies/exception-policies). You require **Admin** or **Code Scanner** role permissions to snooze findings and edit snooze parameters. See [authorization roles](/platform-administration/rbac/authorization-roles) to learn about the different roles Endor Labs offers. To snooze a finding: 1. Open the finding details. 2. Click **Snooze**. 3. Select the most appropriate reason to indicate why you're snoozing the finding. 4. Optionally, select **Expiration** to specify when the finding should reappear. If you set an expiration date, the finding will be automatically un-snoozed by the first scan on the expiration date. 5. Optionally, for vulnerability findings, select **Automatically un-snooze when a fix becomes available** to have the finding reappear after the first scan once a fix becomes available. 6. Optionally, add a comment to provide context for the snooze. 7. Click **Snooze Finding**. A finding can be temporarily snoozed while a fix is in progress, with details such as the reason, expiration date, and remediation timeline recorded for context. Snooze Finding ### View snoozed findings To view snoozed findings: 1. Select **Findings** from the left sidebar. 2. Select **Dismissed** from saved filters and select **Yes**. 3. Select **Snoozed** to view snoozed findings only. 4. Use the filter form to refine results by reason, or expiry range. 5. Click on a snoozed finding to view its details. You can view snooze parameters, including status, expiration date and time, and comments, in the finding details panel. The last updated timestamp shows when you created or last modified the snooze, which helps you track changes and verify if someone else has modified or un-snoozed the finding. Snooze parameters See [Get finding snooze history](/developers-api/rest-api/using-the-rest-api/use-cases#get-finding-snooze-history) to retrieve the snooze history of a finding via the API. ### Un-snooze findings When you un-snooze a finding, it immediately reappears in your findings list and dashboards. The finding becomes active again, and action policies will process it during the next scan. To un-snooze a finding: 1. Select **Findings** from the left sidebar. 2. Select **Dismissed** from saved filters and select **Yes** to view snoozed findings. 3. Click on a snoozed finding to view its details. 4. Click **Edit snooze** and then click **Un-snooze**. Edit or un-snooze finding ### Update snoozed findings To update snooze settings of a finding: 1. Select **Dismissed** from saved filters and select **Yes** to view snoozed findings. 2. Click on a snoozed finding and click **Edit snooze**. 3. Edit snooze settings such as expiration date, reason, or comments, and click **Update Snooze** to save the changes. ## Dismiss findings using an ignore file Ignore files let you dismiss findings by committing a file in your repository. Endor Labs applies them during scan execution, and they only affect the repository version that contains the file (the parent of the scan). Any finding that matches an entry in the ignore file does not appear in the findings list or trigger action policies. You must [allow ignore files to dismiss findings](/platform-administration/configure-system-settings#allow-ignore-files-to-dismiss-findings) in **Settings** > **SYSTEM SETTINGS** > **Developer Workflows** for scans to process ignore files. Ignore files can be in one of two formats: * [**Yaml format**](#ignore-file-yaml-syntax): A list of ignore entries. Each entry specifies the finding by name, dependency, or other fields, plus metadata such as reason, expiration date, and comments. * [**Raw vulnerability IDs**](#ignore-file-plain-text-format): A plain list of vulnerability identifiers (for example, CVE or GHSA), one per line, for vulnerability findings only. This format does not require yaml structure. By default, the supported file path is `.endorignore.yaml`. Your administrator can configure additional files in Developer Workflows. Set up CODEOWNERS for all supported ignore files so that changes require approval before merge. ### Ignore file yaml syntax The ignore file contains entries that specify the findings to suppress during scans. Use the [endorctl ignore](/developers-api/cli/commands/ignore) command to create the file if needed and format the yaml entries automatically. Use the [endorctl validate ignore](/developers-api/cli/commands/validate/ignore) command to validate the file after changes or branch merges. The file must include a top-level `version` and an `ignore` key whose value is a list of entries. Each entry supports the following fields. The following example shows a valid ignore file in yaml format with a version, an ignore list, and entries that use the fields described above. ```yaml expandable theme={null} version: 1.0.0 ignore: - id: endorignore-1 username: alice@corp.com finding_name: Unmaintained Dependency some-package@1.0 reason: risk-accepted expiration_date: 2026-06-01 comments: "Tracking upgrade in JIRA-123" - id: endorignore-2 vuln_id: CVE-2025-12345 parent_name: some-ut-package-name reason: other expire_if_fix_available: true comments: "No fix available and this package is only used for testing" - id: endorignore-3 username: bob@corp.com finding_name: "Potential secret leak Generic API Key: ID #dace33" reason: resolved comments: "I revoked my token" ``` ### Ignore file plain text format You can ignore vulnerability findings by listing the vulnerability IDs in a plain text file. ```shell theme={null} # Ignore list for approved exceptions (AppSec-owned) CVE-2024-12345 GHSA-xxxx-yyyy-zzzz CVE-2023-99999 ``` ### View ignored findings To view ignored findings: 1. Select **Findings** from the left sidebar. 2. Select **Dismissed** from saved filters and select **Yes**. 3. Select **Ignored** to view ignored findings only. 4. Use the filter form to refine results by reason, or expiry range. 5. Click on an ignored finding to view its details. You can view ignore parameters, including status, expiration date and time, comments, ignore file name and entry id in the finding details panel. The ignore parameters available depend on which fields the developers must provide in the ignore file entries. ## Filter dismissed findings Use the following options to filter dismissed findings. * Select **Yes** to view only dismissed findings in the findings table. * Select **No** to hide dismissed findings from the findings table. * Deselect both Yes and No to include dismissed findings in the findings table along with the rest of the findings. * Select **Exception**, **Ignored**, and/or **Snoozed**, to filter by dismissal method. * For exception findings, choose from one of the existing exception policies in the list or search for a specific exception using **Search for Policy Name**. * Select **Reason** to filter dismissed findings by reason. * Select **Expires Within** to filter dismissed findings by expiration time-frame. Dismissed finding filters # Working with finding filters Source: https://docs.endorlabs.com/inventory-insights/findings/finding-filters/index Learn how to implement and use finding filters to search, prioritize, and manage security findings across your organization. Filters enable targeted queries on findings based on attributes such as severity, category, reachability, ecosystem, and policy status. This guide explains how finding filters work, how to apply and combine them effectively, and provides practical examples to support triage, audit, and reporting workflows across your finding inventory. ## How filters work Each filter consists of three parts. * **Key**: The attribute you want to filter (for example, `Severity`, `Category`, and `Ecosystems`). * **Operator**: The comparison logic (for example, `equals`, `in`, and `contains`). * **Value**: The target value to evaluate (for example, `Critical` and `Vulnerability`). Finding filters use standard comparison operators to evaluate criteria. See [Filter operators](/developers-api/rest-api/using-the-rest-api/filters#operators) for detailed information about available operators and their usage when using the API. ## Filter implementation techniques You can use the following filter types to manage your findings effectively. * [Basic filters](#search-for-findings-using-basic-filters): Use the filter bar in the Endor Labs user interface to quickly segment findings by common attributes. * [Advanced filters](#search-for-findings-using-advanced-filters): Use advanced filters to create powerful queries that drill deeper into the dataset to fetch results with a specific context. * [Saved filters](#saved-filters): Save your custom filters for reuse across projects. ### Search for findings using basic filters Use the following basic filters to search for information in your findings. * **Finding Level**: Limit results by finding severity level. * **Dismissed**: Include or exclude dismissed findings. See [Filter dismissed findings](/inventory-insights/findings/dismiss-findings#filter-dismissed-findings) to learn more about filtering dismissed findings. * **Category**: Choose from CI/CD, Malware, license risks, operational risks, RSPM, GitHub Actions, SAST, AI models, containers, secrets, security, supply chain, or vulnerability and view related findings. * **Projects**: Narrow findings by one or more project names. * **Custom Tags**: Narrow down the list based on custom tags. * **Attributes**: Narrow down the list based on a range of factors such as: * if a patch is available to fix the findings * if the vulnerable function is reachable * if the dependency is reachable * if the dependency originates from a current repository or a current tenant * if the dependency is a test dependency * if the dependency's discovery type is manifest, phantom, or segment match * if the finding originates from itself, direct, or a transitive dependency * if the SAST finding is generated by the AI SAST detection agent * if AI SAST analysis has classified the SAST finding as a true positive or false positive * filter the findings by the **Exploited** tag from **CISA KEV** * filter the findings by the **Warn** or **Break the Build** options set in the [action policy](/platform-administration/policies/action-policies#create-an-action-policy-from-template) * **EPSS Probability**: Choose the Exploit Prediction Scoring System (EPSS) score range. * **Ecosystems**: Filter by language or ecosystem. * **Location**: Narrow findings by where they occur (for example, path or location in the repository). * **Confidence**: Narrow findings by detection confidence. * **SAST Languages**: Narrow SAST findings by programming language. * **Container Layers**: Narrow container findings by image layer. * **Remediation**: Narrow vulnerability findings by fix status. * **Endor Patch Available**: Filters findings where an Endor-provided patch is available to fix the vulnerability. * **Recommended Upgrade Available**: Filters findings where a recommended version upgrade is available. * **All Time**: Choose a time range. ### Search for findings using advanced filters For complex queries, use the advanced filter syntax to combine multiple attributes and apply logical operators. Toggle the **Advanced** option in the filter bar to enter API-style filter expressions directly in the Endor Labs application. Search using the advanced filters applies to all the branches of a repository. You can retrieve results from any branch by specifying the relevant context ID or type. See [View findings associated with a project](/inventory-insights/findings#view-findings-associated-with-a-project) for an example of scoping findings to a specific branch. The **Advanced Filters** use the `GetFinding` [API call](/api-reference/findingservice/getfinding) to fetch results. The following table lists the available attributes for finding filters. #### Interactive filter builder #### API filter use cases The following examples demonstrate how to combine these attributes for common security and compliance workflows. Find critical and high-severity findings where a fix is available and the vulnerable function is reachable. ```bash theme={null} spec.level in ["FINDING_LEVEL_CRITICAL","FINDING_LEVEL_HIGH"] and spec.finding_tags contains ["FINDING_TAGS_FIX_AVAILABLE"] and spec.finding_tags contains ["FINDING_TAGS_REACHABLE_FUNCTION"] ``` Identify vulnerability findings with an EPSS score greater than 10% to focus on issues most likely to be exploited in the wild. ```bash theme={null} spec.finding_categories contains ["FINDING_CATEGORY_VULNERABILITY"] and spec.finding_metadata.vulnerability.spec.epss_score.probability_score > 0.1 ``` Retrieve all active, non-dismissed vulnerability findings for a single project. ```bash theme={null} spec.finding_categories contains ["FINDING_CATEGORY_VULNERABILITY"] and spec.project_uuid == "" and spec.dismiss == false ``` List all vulnerability findings from PyPI packages across the namespace. ```bash theme={null} spec.finding_categories contains ["FINDING_CATEGORY_VULNERABILITY"] and spec.ecosystem in ["ECOSYSTEM_PYPI"] ``` Review all dismissed findings across the namespace to verify exception policies are applied correctly. ```bash theme={null} spec.dismiss == true ``` Retrieve findings scoped to a specific branch or repository version by providing the context ID. ```bash theme={null} context.id == "" ``` Find findings tied to CVEs in the CISA KEV database that have no available fix, to assess unmitigatable risk. ```bash theme={null} spec.finding_tags contains ["FINDING_TAGS_EXPLOITED"] and spec.finding_tags contains ["FINDING_TAGS_UNFIXABLE"] ``` Surface supply chain findings that affect only direct dependencies to prioritize the most actionable issues. ```bash theme={null} spec.finding_categories contains ["FINDING_CATEGORY_SUPPLY_CHAIN"] and spec.finding_tags contains ["FINDING_TAGS_DIRECT"] ``` ### Saved filters Saved filters are customizable filter settings that users can create and reuse across projects in Endor Labs. They improve efficiency by eliminating the need to manually recreate filters. You can save the advanced search filters that you created to fetch curated search results. Saved queries are visible in the drop-down list. To create a saved filter: 1. Select **Findings** from the left sidebar. 2. Toggle **Advanced** in the top right corner. 3. Type or build your query in the filter bar. 4. Click **Saved Filters** in the top right corner. 5. Click **Save Current**. 6. Enter a name in the **Choose filter name** field. 7. Click **Save**. Create saved filter #### Manage saved filters To delete a saved filter: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Saved Filters**. 3. Click the vertical three dots on the right side of the filter you want to delete and click **Delete**. To edit a saved filter: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Saved Filters**. 3. Click **Edit** next to the filter you want to edit. 4. You can update the name, query, and tags. 5. Click **Update** to save the updated changes. Update saved filter # Findings Source: https://docs.endorlabs.com/inventory-insights/findings/index View, filter, and manage security findings across your projects and packages. A finding is a discovery of significance made following the completion of a scan. Findings result from the default out-of-the-box implementation of rule sets called [Finding policies](/platform-administration/policies/finding-policies). ## View findings To view different types of findings associated with all projects or packages in your tenant: 1. Select **Findings** from the left sidebar. 2. Search for findings using [basic filters](#search-for-findings-using-basic-filters). 3. Use **Saved Filters** to create and [save](#saved-filters) your frequently used searches, helping you save time. 4. Toggle **Advanced** and search for findings using [advanced filters](#search-for-findings-using-advanced-filters). 5. Use **Table preferences** to select the columns you want to view and customize the appearance of the findings table. 6. Select a finding to view the following details: * Project metadata * Risk details and remediation guidance * Notifications associated with the finding and Jira ticket links * Personalized notes for each finding. You can view notes on findings if you have tenant access. Only users with **Admin** or **Code Scanner** role can add or edit notes. See [authorization roles](/platform-administration/rbac/authorization-roles) to learn about roles and permissions. 7. To apply [exceptions to findings](#dismiss-findings-using-an-exception-policy), select findings and click **Actions** > **Add Exception**. 8. To [export findings](#export-findings), select the findings, and click **Actions** > **Export Selected** or **Export All**. Findings UI ## View findings associated with a project To view the findings associated with a project: 1. Select **Projects** from the left sidebar. 2. Select the project for which you want to view the findings. The Findings page includes the list of findings specific to the project. 3. Review the list of findings. Click the finding to see its details. 4. Use **Grouped By** to group findings by attributes such as dependency, location, package, CWE, tags, code owner or rule name to filter and manage them collectively. 5. A drop-down menu at the top left of the page shows the repository's default branch. Choose a different branch to view its findings. * In the following example, `main` is the default branch. Applying filters with the context ID for `main` shows results specific to branch. To scan from the default branch, run the following command: ```bash theme={null} endorctl scan --path=. ``` Branch dropdown * Similarly, if there is another branch named `local-branch`, switching to that branch shows results specific to the branch. To scan the branch, run the following command: ```bash theme={null} git checkout local-branch endorctl scan --path=. ``` Check **Projects** to see the default branch of your project. To change the default branch, use `--as-default-branch` while performing the `endorctl` scan. See [scanning strategies](/scan/sca/scanning-strategies) for information on testing and monitoring different versions of your code. ## Finding attributes Finding attributes are characteristics or properties associated with each discovered issue or result obtained from a scan. These attributes could include the following details and metadata. ## Filter findings Use filters to narrow findings and focus on the results most relevant to your workflow. Filters help you organize findings by attributes such as severity, category, project, status, repository context, and other finding metadata so that you can investigate, triage, and remediate findings more efficiently. You can use the following filter types to manage findings effectively. * **Basic filters**: Use the preset filters to quickly narrow findings using common attributes such as severity, category, project, and status. * **Advanced filters**: Use advanced filters to create complex queries and combine multiple conditions based on repository context, branches, tags, and other finding attributes. See [Finding filters](/inventory-insights/findings/finding-filters) for more information. ## View Remediations If you enable [upgrade impact analysis](/risk-remediation/upgrade-impact-analysis), you can view the remediation recommendation when you select a finding, if available. Click **View Details** to view the details of the [remediation recommendation](/risk-remediation/upgrade-impact-analysis#view-remediation-recommendations). Click **View Full Recommendation** to view all available upgrade paths. # Manage findings Source: https://docs.endorlabs.com/inventory-insights/findings/manage-findings/index Configure finding and action policies, export findings to CSV, and organize findings with tags. Managing findings shapes what Endor Labs reports, how your teams respond, and how you organize issues over time. After you [view and filter findings](/inventory-insights/findings), use [finding policies](/platform-administration/policies/finding-policies) to control what is surfaced and [action policies](/platform-administration/policies/action-policies) to automate next steps when criteria match. Export findings when you need data outside the product, and use tags to group and search efficiently. Manage findings to control how findings are handled, organized, and acted on across your environment. After you view and filter findings use [finding policies](/platform-administration/policies/finding-policies) to control which findings are surfaced and [action policies](/platform-administration/policies/action-policies) to automate actions when findings match specific criteria. You can also export findings for external analysis and apply tags to organize and search findings more efficiently. ## Create Jira issues from Findings Create Jira issues manually from the Findings for one or more items. This enables you to create and assign workflow issues without relying on action policies or scan cycles. Endor Labs records them as **On-demand notification** in **Notifications**. If issue creation fails, you can also review the error details. See [Notifications](/inventory-insights/notifications) to learn more. Ensure that you have a [Jira notification integration](/integrations/jira) configured in Endor Labs to create issues in your Jira board. If a finding already has a Jira issue in the selected board that was created manually, you cannot create another one in that board. If the existing issue was created by an [action policy](/platform-administration/policies/action-policies), then you can create a new issue for that finding. When a finding is resolved in a subsequent scan, Endor Labs updates all linked Jira issues to your integration's resolved state. That applies to manually created issues and to issues created through action policies. ### Create a Jira issue for a single finding You can create a Jira issue for a single finding from the **Findings** view. 1. Select **Findings** from the left sidebar. 2. In **Table preferences**, turn on the **Integration - Jira** column. 3. Click **Create JIRA ticket** in the finding's row. 4. Select a Jira integration configured in your namespace. Ensure the integration is available in the same namespace as the findings. 5. Click **Create Issue**. After creation, you can use the issue URL to open it in Jira and view its details. ### Create Jira issues for multiple findings at once You can create Jira issues for multiple findings from the **Findings** view. 1. Select **Findings** from the left sidebar. 2. In **Table preferences**, turn on the **Integration - Jira** column. 3. Search for and select the findings to create Jira issues for. You can select up to 10 findings at a time. 4. Click the vertical three dots and select **Add Jira Notifications**. 5. Select a Jira integration configured in your namespace. Ensure the integration is available in the same namespace as the findings. 6. Click **Create Issue**. After creation, you can use the issue URLs to open them in Jira and view their details. When creating Jira issues for multiple findings, Endor Labs processes each finding independently. If a finding already exists in the selected board, it is skipped while the rest are created successfully. Jira issues from findings ## Export findings You can export finding details to a CSV file for offline analysis. 1. Select **Projects** from the left sidebar. 2. Search for and select a project and select **Findings**. 3. Search for findings using advanced or basic filters. 4. Select the findings and click the vertical three dots. 5. Choose **Export Selected** or **Export All** and select the fields that you want to include in the CSV file. 6. Click **Export to CSV** to download the file. ## Apply tags to findings Tagging findings helps you organize, prioritize, and filter issues efficiently. You can tag findings in a finding policy or while running the endorctl scan. ### Using finding policies You can define custom tags in a finding policy, which automatically apply to findings that match its conditions. See [Finding policies](/platform-administration/policies/finding-policies) for more information. To add custom tags: 1. Select **Policies & Rules** from the left sidebar. 2. Follow the steps to [create a finding policy](/platform-administration/policies/finding-policies#create-a-finding-policy-from-template). Ensure to add your choice of custom tags in **Finding Custom Tags**. You can also update an existing policy. 3. Click **Create Finding Policy**. After you create or update a finding policy, rescan your project to apply the custom tags to your findings. ### Through the CLI When scanning projects using endorctl, you can tag all the findings generated within the scan scope using the `--finding-tags` flag. To scan and tag all findings of an endorctl scan: ```bash theme={null} endorctl scan --finding-tags=findings-tag-name ``` ### View tagged findings To filter and view the findings by their tags: 1. Select **Projects** > **Findings** from the left sidebar. 2. Enter the tag in the search bar to filter and view findings by tag name. Search findings tags on UI # Inventory & Insights Source: https://docs.endorlabs.com/inventory-insights/index View and analyze your projects, findings, packages, dependencies, and security posture. Inventory & Insights provides a comprehensive view of your software assets and security analysis results. This section covers everything from organizing your projects and namespaces to viewing detailed findings, tracking dependencies, and visualizing your security posture through dashboards. Visualize analytics, security posture, and vulnerability insights Export analytics and findings as JSON or PDF for offline review and sharing Organize your tenant into logical partitions for teams and business units View and manage your scanned source code repositories View and triage security findings across your projects View packages maintained as part of your projects Explore dependencies across all projects in your namespace View and manage license information for legal and compliance review Review past scan details and track security posture over time View pull request scan results and CI/CD integration status View and manage policy notifications and alerts # Licenses Source: https://docs.endorlabs.com/inventory-insights/licenses/index View and manage license information across projects for legal and compliance review. Beta
Open source dependencies can introduce license obligations that may affect how software is used, modified, or distributed. Reviewing license information helps teams identify potential compliance concerns, verify attribution requirements, and maintain visibility into approved and restricted licenses across the organization. You can view and manage license information across your projects, edit license data, and generate Notice reports for distribution. ## View licenses To view licenses: 1. Select **Inventory** from the left sidebar. 2. Select **Licenses** to view the list of licenses. You can view the license name, OSI approval status, license type, and project count. Licenses list 3. Use **Search license Name** to filter the list or search for a specific license. 4. Use the **OSI**, **Projects**, and **Type** filters to narrow the list. 5. Select a license row to view the following details: * **TYPE**: License type for the selected license (for example, Permissive, Copyleft). * **OSI**: Whether the license is Open Source Initiative approved. * **PROJECTS**: List of projects that use this license. Expand a project to view the license text for each dependency in that project that uses this license. View license details ## View licenses associated with a project To view licenses for a specific project: 1. Select **Projects** from the left sidebar and select the project for which you want to view licenses. 2. Select **Inventory** and select **Licenses** from the dropdown to view the list of licenses for that project. Licenses list for a project 3. Select a license to view the following information. * **Type**: Shows the type of license. * **OSI**: Shows whether the license is OSI approved. * **Full License Text**: Shows the license text for the selected dependency version. You can view: * **Declared License**: The license declared by the dependency, along with a reference to where it is defined. * **Discovered License**: The license detected during scanning, with a link to the exact file where the license content was found. Click **Show full text** to expand the full text of either license. Project license details ## Edit license information You require **Admin** role permissions to edit dependency license data. See [authorization roles](/platform-administration/rbac/authorization-roles) to learn about the different roles Endor Labs offers. You can edit license information to correct or override license data when scan results or package metadata are incomplete or inaccurate. Editing license information helps you to: * Fix misclassified, missing, or unknown licenses so the effective license reflects the expected result. * Update copyright, notice text, or license expressions used in generated Notices files. * Standardize SPDX identifiers or expressions across projects. To edit license information from a dependency: 1. Select **Projects** from the left sidebar and select a project. 2. Select **Inventory** and select **Dependencies** from the dropdown to view the list of dependencies for that project. 3. Select a dependency and click **Edit**. 4. The **Edit Dependency** page shows dependency metadata at the top, for example, name, source code location, and package location. 5. Under **Declared licenses** and **Discovered licenses**, click **Add License** and search for a license to add. You can also edit existing licenses. 6. Under **Copyrights**, click **Add Copyright** to add copyright statements. 7. Optionally, select **Propagate dependency edits to all child namespaces** to apply the same changes to related namespaces. 8. Click **Save Dependency** to save the changes. Edit dependency licenses ## Generate a Notice report A Notice report lists open source dependencies with their license texts, copyright notices, and source code locations. You must include a Notice report when you distribute software that contains open source dependencies. To generate a Notice report from the command line, see [license-notice-report generate](/developers-api/cli/commands/license-notice-report#generate). To generate a Notice report: 1. Select **Projects** from the left sidebar and select the project for which you want to generate a report. 2. Click **Export** > **Notice Report**. Generate Notice report 3. Under **File Format**, choose the output format from either HTML or plain text. 4. Select **Group By** to choose how the report is organized: * **License**: Lists each distinct license once, followed by all dependencies using that license. Use this for compact reports when many dependencies share the same license. * **Dependency**: Lists each dependency with its license text inline. Use this when each dependency has a different license. 5. Under **Scope**, select **Add More** and choose one or more packages for the report. Test dependencies are excluded. Projects can contain multiple packages with several manifests. The report includes license and copyright information for dependencies used by the selected packages. 6. Click **Create Report** to generate and download the report. ### View Notice reports To view Notice reports: 1. Select **Reports** from the left sidebar. 2. Select a report to view its details such as file format, group-by option, and package scope. 3. To download a report, click the three vertical dots and click **Download**. 4. To delete a report, click the three vertical dots and click **Delete**. See [Reports](/inventory-insights/reports) for more information on managing reports. # Namespaces Source: https://docs.endorlabs.com/inventory-insights/namespaces/index Organize your tenant into logical partitions based on organizational units, business units, or teams. Namespaces in Endor Labs define a way to group projects and create logical partitions in an organization based on organizational units, business units, project requirements, or teams. Using namespaces, administrators can: * Define hierarchy and control access to project resources within a namespace. * Establish policy governance by defining the rules of engagement and setting different or same guardrails across namespaces. ## Namespaces in an organization In Endor Labs, you can partition each tenant into multiple namespaces and further divide each namespace into sub-namespaces called child namespaces. Each namespace has its own authorization rules and integrations. Child namespaces inherit settings, policies, and features from their parent namespace but can also define their own authorization rules, policies, and configurations. This structure helps organizations model hierarchical environments, with each level managing its own access controls and operational settings. When you access your tenant, Endor Labs includes data from all child namespaces in the dashboard by default, such as vulnerabilities, dependencies, packages, and more. In **namespace**, toggle the setting to **All child namespaces excluded** to exclude child namespaces and view data and metrics for only the selected namespace. namespaces toggle When you sign in to Endor Labs for the first time, create a tenant for your organization, such as `abccorp`. * Now you can create logical separations in the form of namespaces for different business units in your organization, such as Security Business Unit (`security-bu`), Datacenter Business Unit (`datacenter-bu`), and Orchestration Agent Business Unit (`orchestration-agent-bu`), inside your main tenant `abccorp`. * You can further partition the Security Business Unit into sub-namespaces, such as the Development team (`dev-team`), Finance Team (`finance-team`), and Testing Team (`testing-team`). Namespaces Example * There can be multiple namespaces within `abccorp`. For example, the `dev-team` namespace that hosts projects belonging to the development team of the Security Business Unit and the `test-team` namespace that hosts projects belonging to the testing team of the Security Business Unit. ## Use namespaces for authorization Large enterprises with multiple business units, teams, or groups can assign different namespaces to different groups and apply authorization policies that restrict access to specific groups. This ensures least privilege access to critical information is available in the organization. Organizations can also provision namespaces to provide read access to security teams in specific namespaces while they provide write access to AppSec teams for managing policies. * Create an authorization policy giving users in the development team of the security business unit permissions to scan their projects. Users from group `@developers.abccorp.ai` can have code scanner permissions for the namespace `dev-team`. * Users from group `@applicationsecurity.abccorp.ai` can have policy editor permissions for the namespace `dev-team`. The developers can scan the code, and the application security professionals can define the policies for code compliance. * The application security professionals can also choose to define the policies at the tenant level `abccorp` and choose to apply the same policies to all the child namespaces. This way, they won't need to create policies individually for every child namespace. The development team inherits the policies from the organization and won't be able to modify them. They can, however, add additional policies that are specific to engineering to their namespace `dev-team` and define specific rules and conditions applicable only to them. ## Use namespaces for policy governance Administrators can use namespaces effectively for policy governance and make sure that teams in their organization adhere to industry-wide policy standards enforcing compliance. Let us assume that the application security team in `ABCcorp` wants to define organization-wide rules for code compliance, vulnerability management, and secret detection. They also need Jira tickets filed for all cases. The application security engineers can create the following objects at the `ABCcorp` tenant level and propagate these objects to all the namespaces under `abccorp` so that it applies to the entire organization. * Define action policy to break the build when scans detect critical vulnerabilities. * Define action policy to warn the user of detected code compliance misconfigurations. * Define action policy to break the build when scans detect valid secret tokens in their code. * Create Jira tickets and notify the appropriate team to take remediation measures. ## Create a namespace To create a namespace in your tenant: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Namespaces**. 3. Click **New Namespace**. 4. Enter a title and description for the namespace. The title can have a maximum of 32 characters and must contain only lowercase letters (a-z), numbers (0-9), and characters (\_-). 5. Enter tags that you want to associate with this namespace. Tags can have a maximum of 255 characters and must contain letters (A-Z), numbers (0-9), and characters (=@\_.-). 6. Click **Create Namespace**. ## Edit a namespace You can choose to modify the description of a namespace or include tags for it. You can't modify its title after you create a namespace. To edit details of a namespace in your tenant: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Namespaces**. 3. Choose the namespace and click **Edit**. 4. Edit the description or include tags for the namespace. 5. Click **Update Namespace**. ## Delete a namespace Deleting a namespace permanently deletes all its child namespaces and its projects. To delete a namespace: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Namespaces**. 3. Choose the namespace and click **Delete**. 4. Select and confirm the deletion. 5. Click **Delete Namespace**. ## Data propagation from parent to child namespaces Data propagation defines how child namespaces inherit data from their parent namespace. * **Finding Policies**: When you create a namespace, all the finding policies in the parent are **inherited** by the child namespaces. Any new finding policy you create in the parent, you can choose to apply it to the child namespaces by selecting **Propagate this policy to all child namespaces**. * **Action Policies**: When you create a namespace, all the action policies in the parent are **inherited** by the child namespaces. Any new action policy you create in the parent, you can choose to apply it to the child namespaces by selecting **Propagate this policy to all child namespaces**. * **Remediation Policies**: When you create a namespace, all the remediation policies in the parent are **inherited** by the child namespaces. Any new remediation policy you create in the parent, you can choose to apply it to the child namespaces by selecting **Propagate this policy to all child namespaces**. * **Exception Policies**: When you create a namespace, all the exception policies in the parent are **inherited** by the child namespaces. Any new exception policy you create in the parent, you can choose to apply it to the child namespaces by selecting **Propagate this policy to all child namespaces**. * **Package Manager Integrations**: Package manager integrations of the parent are **not inherited** by the child namespaces. Any new package manager integration you create in the parent, you can choose to apply them to the child namespaces by selecting **Propagate this package manager to all child namespaces**. * **Integrations**: Integrations in the parent are **not inherited** by the child namespaces. * **Authorization Policies**: Authorization policies of the parent are **inherited** by all its child namespaces. You can choose to group the authorization policies of the child namespaces in their parent namespace and manage them easily. * **Secret Rules**: You can choose to apply custom secret rules created in the parent to its child namespaces by selecting **Propagate this rule to all child namespaces**. * **API Key**: You can create an API key in a namespace and select **Propagate this rule to all child namespaces** to apply the key to all child namespaces. ## Tenant and namespace terminologies Tenant is the top-level entity under which you can create namespaces and child namespaces. To denote a namespace, always use its fully qualified name. Fully qualified name for a namespace is in the format `tenantname.namespacename`, and child namespace is in the format `tenantname.namespacename.childnamespacename`. * In this example, the tenant is `abccorp` and its child namespaces are `abccorp.security-bu`, `abccorp.datacenter-bu`, and `abccorp.agent-bu`. The child namespaces of `abccorp.security-bu` are `abccorp.security-bu.dev-team`, `abccorp.security-bu.testing-team`, and `abccorp.security-bu.finance-team`. * Consider a tenant named `acme` with a child namespace `dev`, which in turn has a child namespace `app`. The fully qualified namespace for `app` is `acme.dev.app`. # Notifications Source: https://docs.endorlabs.com/inventory-insights/notifications/index Learn how to view, search, and manage policy notifications in Endor Labs. Notifications are alerts generated when findings match the criteria defined in your action policies or remediation policies. When you [create Jira issues from Findings](/inventory-insights/findings#create-jira-issues-from-findings), Endor Labs creates an **on-demand notification** for each attempt. **On-demand notification** is the policy value for those entries, including when issue creation fails. Endor Labs sends notifications to your configured notification integrations, such as email, Slack, Jira, webhooks, Vanta, or GitHub PR comments. The notifications view gives you centralized visibility across integrations. It helps you debug and recover from delivery failures, track your security work queue through open and resolved states, and review an audit trail of all notifications. ## Prerequisites To receive notifications, you must: 1. [Set up notification integrations](#notification-integrations) 2. Configure an [action policy](/platform-administration/policies/action-policies) or a [remediation policy](/platform-administration/policies/remediation-policies) with the **Send Notification** action. ## View all notifications To view all notifications in your namespace, select **User menu** > **Notifications** from the left sidebar. Notifications fall into four categories: * **Open**: Notifications for findings that are still open and require attention. * **Resolved**: A notification moves to resolved when the finding associated with it is either resolved or deleted. * **Dismissed**: Notifications that you dismissed to stop Endor Labs from processing and updating them. * **All**: All notifications in your namespace, regardless of their status. You can view the following details for each notification: * **Opened**: Elapsed time since Endor Labs created the notification. * **Policy**: Action policy or remediation policy that triggered the notification. [Jira issues created manually from findings](/inventory-insights/findings#create-jira-issues-from-findings) are recorded as **On-demand notifications**. * **Project**: The project associated with the notification. * **Last Evaluated**: The elapsed time since the action policy or remediation policy was last evaluated. * **Violations**: The number of policy violations that triggered this notification. * **Namespace**: The namespace where Endor Labs creates the notification. * **Channels**: The notification channels configured in your namespace that receive alerts, such as Jira, Email, Slack, Vanta, Webhooks, and GitHub PR. When a notification has an error, a red triangle appears next to it. Click the notification to view more details about the error. Notifications ### Search notifications You can search notifications by the policy name or Jira issue key. * Policy name: Enter the action policy or remediation policy name to find all notifications associated with that policy. For example, search for `SAST` to find all notifications triggered by the SAST action policy. * Jira issue key: Enter a Jira issue ID in the format `PROJECT-KEY-NUMBER` to find all notifications associated with that Jira issue. For example, searching for `BUG-235` shows notifications linked to the Jira issue BUG-235. ### Filter notifications Use filters to refine notifications by time range, projects, notification channels, or error status. You can use the following filter options: * **All Time**: Filter notifications by creation date. You can select from the following options: **Last Day**, **Last week**, **last month**, **last 60 days**, **last 90 days**, **All Time**, or you can customize the time range. * **Projects**: Enter a project name in your namespace and select it. You can select multiple projects to view notifications from those projects. * **Channels**: Filter notifications by notification channels such as Slack, Jira, Email, webhooks, Vanta, and GitHub PR. The channels displayed depend on the notification integrations set up in your namespace. * **Has Errors**: Filter to show only notifications that have errors in their notification delivery. This includes errors such as failed delivery attempts, configuration issues, or unsupported scenarios. ## View notification details Each notification contains detailed information about the security event or policy violation that triggered it. This includes metadata about the associated project, the findings that caused the notification, and any actions taken in response. You can also view any errors that occurred during notification delivery. To view notification details: 1. Select **User menu** > **Notifications** from the left sidebar. 2. Select a notification. 3. Select **Overview** to view key information about the notification such as its metadata, triggered actions, and associated findings. * **Notification metadata**: Project associated with the notification, the date and time when Endor Labs opened the notification, the date and time when the policy was last evaluated, and the notification UUID. * **Actions triggered by this notification**: Lists all actions the notification triggered, including issue IDs created in external systems, and links to external tickets or pull requests. * **Findings that triggered this notification**: The findings that matched the action policy or remediation policy criteria and that triggered this notification. 4. Select **Issues** to view error messages and troubleshoot notification delivery problems. View details of notifications ## Manage notifications Use actions on each notification to view details, navigate to the related policy, or dismiss notifications. To navigate to the policy which triggered a notification: 1. Select **User menu** > **Notifications** from the left sidebar. 2. Click the vertical three dots on the notification whose policy you want to view. 3. Select **Go to Policy** to view and update the policy. ### Dismiss notifications Dismiss a notification to pause all further posting, processing, and updates associated with it. Endor Labs also stops sending updates to existing Jira tickets, emails, Slack messages, or webhooks, even if the underlying finding changes or gets resolved. You can view dismissed notifications in the **Dismissed** category. You can dismiss any notification from **Open** or **Resolved**. To dismiss a notification: 1. Select **User menu** > **Notifications** from the left sidebar. 2. Click the vertical three dots on the notification you want to dismiss. 3. Select **Dismiss Notification**. To dismiss multiple notifications at once: 1. Select **User menu** > **Notifications** from the left sidebar. 2. Select the notifications you want to dismiss. 3. Click **Actions** and select **Dismiss Notification**. ### Undismiss notifications When you undismiss a notification that is in **Open** state, Endor Labs re-evaluates it in the next scan cycle or schedule based on the current state of the underlying finding. It then processes the notification accordingly, such as by sending updates to Jira, email, Slack, or webhooks if the policy applies. To undismiss a notification: 1. Select **User menu** > **Notifications** from the left sidebar. 2. Select **Dismissed**. 3. Click the vertical three dots on the dismissed notification. 4. Select **Undismiss Notification**. To undismiss multiple notifications at once: 1. Select **User menu** > **Notifications** from the left sidebar. 2. Select **Dismissed**. 3. Select the notifications you want to undismiss. 4. Click **Actions** and select **Undismiss Notification**. ## Notification integrations You must configure notification integrations to receive notifications. These integrations define the destinations that receive notifications when action policies or remediation policies trigger them. Endor Labs supports integrations like email, Jira, Slack, Vanta, and other tools. * [Email integration](/integrations/email) * [Jira integration](/integrations/jira) * [Slack integration](/integrations/slack) * [Webhooks](/integrations/webhooks) * [Vanta integration](/integrations/vanta) * [GitHub PR remediation](/risk-remediation/automated-pull-requests) * [GitHub PR comments](/scan/pr-scans/pr-comments) # Packages Source: https://docs.endorlabs.com/inventory-insights/packages/index Browse the buildable units Endor Labs discovers in your projects, and review their resolution and reachability status. Packages are the buildable units of first-party code Endor Labs discovers inside a project. Each package corresponds to a manifest in your repository, such as `pom.xml`, `package.json`, or `go.mod`. Use the Packages page to confirm Endor Labs discovered every package you expect to scan, and to track whether dependency resolution and reachability analysis succeeded for each one. ## What Endor Labs tracks for a package For each package, Endor Labs records: * **Versions**: Snapshots taken whenever a scan runs against a different commit, branch, or release of the source. Versioning lets you compare the same package across branches, releases, or scheduled scans. * **Dependencies**: The other packages this package consumes, mostly third-party. See [Dependencies](/inventory-insights/dependencies) to review the inventory and Endor Scores. * **Dependents**: Other packages in your tenant that consume this package. Use dependents to communicate with downstream consumers when you change a version. * **Findings**: Security findings derived from rule evaluations against the package and its dependencies. ## How packages relate to projects and repositories A project in Endor Labs represents a source code repository. A single repository typically contains one or more packages. For example, a monorepo can hold dozens of npm or Maven packages, each declared by its own manifest. When Endor Labs scans a project, it inventories every package it can build and tracks each one independently. ## Package discovery and lifecycle Endor Labs discovers packages during a project scan, whether the scan runs from a CI/CD pipeline, on a schedule, or as an ad hoc `endorctl scan` command. For each manifest it finds, Endor Labs builds the package, resolves its dependencies, and generates a call graph where the language and package manager support it. A rescan refreshes the package inventory and updates dependency resolution and reachability results. Rescans run automatically on every CI/CD pipeline scan and on the cadence you configure for scheduled scans. ## Packages and dependencies The Packages page and the Dependencies page answer different questions about your inventory. * **Packages** are the units of first-party code your team owns. They live in your repositories, and Endor Labs scans them as part of your projects. * **Dependencies** are the third-party code those packages consume. Endor Scores, reachability states, and findings on third-party code all live on the Dependencies page. See [Dependencies](/inventory-insights/dependencies) to review the third-party packages your projects consume and how Endor Labs scores them. ## View packages in a project 1. Select **Projects** from the left sidebar. 2. Search for and select a project to review. 3. Select **Packages** under **Inventory** to view every package Endor Labs maintains for the project, along with any findings. Packages list for a project Each row shows: * **Package Name**: The name of the package, with the package manager icon. * **Dependency Resolution**: Status icon showing whether dependency resolution succeeded. * **Reachability Analysis**: Status icon showing whether call graph generation succeeded. * **Dependencies**: The number of dependencies in the package. * **Findings**: The number of findings associated with the package. * **Created**: The date and time when Endor Labs first discovered the package. * **Last Scanned**: The date and time of the most recent scan. The following table describes the **Dependency Resolution** status icons. | Status | Description | | -------------- | ---------------------------------- | | ▲ | Error during manifest scan | | ◐ | Error during dependency resolution | | ● | Dependency resolution succeeded | The following table describes the **Reachability Analysis** status icons. | Status | Description | | -------------- | ------------------------------------------------------ | | ▲ | Error during call graph generation | | ● | Call graph generation succeeded | | ■ | Call graph generation isn't supported or isn't enabled | Select a package to open its detail view, where you can review its dependencies, findings, and Endor Scores. See [Dependencies](/inventory-insights/dependencies) to learn how dependency details and scores work. For C and C++ packages, you can visualize the source files where each dependency was identified during scanning. See [View dependency file locations](/scan/sca/c#view-dependency-file-locations) to explore the file paths Endor Labs detected. ## Filter packages Use filters to narrow the package list to a specific ecosystem or status. On the **Packages** page, apply the **Ecosystem**, **Dependency Resolution**, or **Reachability Analysis** filter to narrow the results. To sort, click the **Package**, **Created**, or **Last Scanned** column header. The sort order toggles between ascending and descending each time you click. Filter packages by ecosystem and status ## Delete a package Delete packages you no longer need from your project inventory. Deleting a package also removes every finding associated with it. 1. On the **Packages** page, select the vertical three dots in the package row, then select **Delete**. 2. Click **Delete** to confirm. Delete package confirmation Deleting a package removes its findings from the project. This action can't be undone. # PR runs Source: https://docs.endorlabs.com/inventory-insights/pr-runs/index View the history of PR scans performed on a project. PR runs provide a detailed view of security scans performed on pull requests before you merge them. They help you assess the security impact of code changes and identify issues early in the development cycle. You can use them to verify merge readiness, ensure compliance, and troubleshoot scan failures with full context on vulnerabilities, policy violations, and dependency issues. 1. Select **Projects** from the left sidebar. 2. Search for and select a project to review. 3. Select **PR RUNS** to review the past scans. * **List of Scans**: View all past PR scans, including details such as the scan time, duration, scan type, and tags. * **Ref**: The Git reference identifying the scanned commit or branch. For Endor Labs SCM Apps, pre-merge pull request scans use a named ref (for example, `pr/1259`), while merge commit scans use a commit SHA. * **Findings Summary**: Review the number of security findings, categorized by severity: Critical, High, Medium, or Low. * **Commit Details**: Each scan maps to a specific commit SHA, allowing users to track security issues to specific code changes. * **Scanned By**: Identifies the user or system that initiated the scan. * **Filtering & Search**: You can filter scans by status, scan type, and time range. You can search by tags, commit SHA, or specific include or exclude file paths. For example, you can select **Container** as a scan type from the dropdown list. Pull request scans history 4. Select a record to view general information about the scan or its logs. * **View Findings**: Displays security findings associated with the scan. Findings are not recorded in case of scan failures. * **View Scan Result**: Displays scan information, issue logs with error details, and additional scan data. * **Overview**: Displays general scan information such as the scan status, result UUID, detected programming languages, system details, and versions of key development tools used in the environment. * **Issues**: Displays additional errors and warnings from the scan. * **Logs**: Monitor scan logs, even while scans are running, and filter by severity level, with selectable log severity from Emergency, Alert, Critical, Error, Warning, Notice, Info, or Debug for in-depth debugging and policy evaluations. You can access scan logs and toolchain details for projects onboarded through Endor Labs cloud using the GitHub, GitLab, or Azure DevOps Apps. The log levels in the selected scan result determine the available log severities. Pull request scans history logs # Projects Source: https://docs.endorlabs.com/inventory-insights/projects/index View and manage your source code repositories scanned by Endor Labs. Projects in Endor Labs represent your source code repositories. When you scan a repository, Endor Labs creates a corresponding project. Select **Projects** from the left sidebar to view a list of all projects in your namespace. Projects You can view the following details in the Projects list: * **Source Code Management Platform** - The icon that represents the source code management platform like GitHub, GitLab, Azure DevOps and Bitbucket. * **Project** - The name of the project, shown as `SCM Organization/Project Name`. * **Findings** - The condensed view of the number of critical, high, medium, and low severity findings in the project. * **Tags** - The tags associated with the project. * **Packages** - The number of packages in the project. * **Dependency Resolution Status** - The percentage of packages that have been fully analyzed with no dependency resolution errors. * **Reachability Analysis Status** - The percentage of packages eligible for reachability analysis that have been fully analyzed with no call graph errors. * **Last Scan** - The elapsed time since the project was last analyzed by Endor Labs. To sort projects by any column, click the column header. The sort order toggles between ascending (A–Z or oldest to newest) and descending (Z–A or newest to oldest), depending on the column type. ## View project details Select a row to view the project details, such as the project metadata, finding details, and tools associated with the project. Project Details ## View project findings Click on **Project** to view the project findings. See [Findings](/inventory-insights/findings) for more information. You can also scan your projects for AI models. See [AI model findings](/secure-ai-coding/ai-model-discovery) for more information. ## View packages in a project Select **Packages** under **Inventory** to view the list of all packages maintained as part of your project. See [Packages](/inventory-insights/packages) for more information. ## Review past scan details You can view the history of scans performed on a project, which enables you to review the security posture of your project over time. See [Scan history](/inventory-insights/scan-history) for more information. ## View dependencies You can view all the dependencies associated with all the projects in your namespace. See [Dependencies](/inventory-insights/dependencies) for more information. ## Filter projects Filters refine the projects view by applying conditions based on project metadata and scan results. For example, you can filter projects by name, tags, scan date, or number of critical findings. You can combine multiple filters to narrow down results based on multiple conditions in a single query. See [Project filters](/inventory-insights/projects/project-filters) to learn how to implement these filters effectively. # Working with project filters Source: https://docs.endorlabs.com/inventory-insights/projects/project-filters/index Learn how to implement and use project filters to search, prioritize, and manage projects across your organization. Filters enable targeted queries based on attributes such as severity, package ecosystems, dependency resolution, and platform source. This guide explains how filters work, how to apply and combine them effectively, and provides practical examples to support triage, audit, and reporting workflows across large codebases. ## Access project filters Perform the following steps to apply filters to the project list. 1. Select **Projects** from the left sidebar. 2. Filter your projects using the list of available filters in the filter bar. 3. Toggle the **Advanced** option in the filter bar to apply API-style filters. You can combine multiple filters to create more specific searches and narrow down the project list based on multiple criteria. ## How filters work Each filter consists of three parts. * **Field**: The attribute you want to filter (for example, `Package Count` and `Platform Source`). * **Operator**: The comparison logic (for example, `equals`, `greater than`, and `in`). * **Value**: The target value to evaluate (for example, `npm` and `100`). Project filters use standard comparison operators to evaluate criteria. See [Filter operators](/developers-api/rest-api/using-the-rest-api/filters#operators) for detailed information about available operators and their usage. When you apply multiple filters, the system combines them using logical AND operations across filters for different fields and logical OR operations across filters for the same field. For example: * **Filter 1**: `Package Ecosystems contains: npm` * **Filter 2**: `Platform Source in: GitHub` * **Filter 3**: `Package Count: greater than 1` * **Filter 4**: `Reachability Analysis Status greater than or equal to: 90%` Multiple filters This combination returns only projects that use npm packages, are from GitHub, have more than one package, and have a reachability analysis status of at least 90%. ## Filter implementation techniques You can use the following filter types to manage your projects effectively. * [Preset filters](#preset-filters): Use predefined UI-based filters to quickly segment projects by common attributes. * [Filter projects using API](#filter-projects-using-api): Use advanced syntax for complex queries and logical combinations. ### Preset filters The following examples demonstrate how to apply preset filters for common project scenarios. #### Filter projects by custom tags Use custom tags to filter projects based on environment or predefined labels assigned during project initialization or scan configuration. For example, to view only projects related to SAST, use the `Custom Tags contains: sast` filter. filter by custom tags #### Filter projects by findings severity Prioritize remediation efforts by filtering projects based on the severity of security findings. You can select from **Critical (C)**, **High (H)**, **Medium (M)**, or **Low (L)** severity filters to target different priority levels. For example, to identify projects with critical findings, select the **C** filter. filter by severity #### Filter projects by package ecosystem Use package ecosystem filters to segment projects by language or package manager. Apply targeted policies, such as stricter vulnerability thresholds for JavaScript or license compliance checks for Java. For example, to focus on PHP projects for a security assessment, use the `Package Ecosystems contains: Packagist` filter. filter by package ecosystem #### Filter projects by source platform Use platform source filters to segment projects by their source platform and correlate findings with platform-native security tools like GitHub's Dependabot alerts or GitLab's vulnerability scanning. For example, to identify projects analyzed from GitLab, use the `Platform Source in: GitLab` filter. filter by source platform #### Filter projects by dependency resolution quality Use dependency resolution status to identify projects with resolution issues that impact security analysis accuracy. You can filter by a single value or a range of percentages. For example, to identify projects with poor dependency resolution, use the **Range** filter to find projects with `Dependency Resolution Status greater than 0% and less than 50%`. filter by resolution #### Filter projects by scan timestamp Use last scanned filters to identify projects with stale security data that require fresh scans for current security posture. You can select from predefined time ranges or use the calendar to select a specific date. For example, to identify projects scanned within the last 24 hours, use the `Last Scanned: Last Day` filter. filter by last scanned #### Filter projects by complexity Identify projects based on their size and complexity, which may require different levels of security attention and resources. For example, to focus on large projects with extensive dependency trees, use the `Package Count: greater than 100` filter. filter by complexity #### Filter projects by reachability analysis status Use reachability analysis status to identify projects based on the success rate of call graph generation and reachability analysis. You can filter by a single value or a range of percentages. For example, to identify projects with successful reachability analysis, use the `Reachability Analysis Status greater than or equal to: 90%` filter. filter by reachability status ### Filter projects using API For complex queries, use the advanced filter syntax to combine multiple attributes and apply logical operators. Use the [Project filter builder](#interactive-filter-builder) to assemble conditions interactively. The following table lists the available attributes for project filters. #### Interactive filter builder #### API filter use cases The following examples demonstrate how to combine these attributes for common security and compliance workflows. Find GitHub projects with more than 5 critical findings and a reachability analysis status below 80%. ```bash theme={null} spec.platform_source == PLATFORM_SOURCE_GITHUB and spec.finding_counts.critical > 5 and spec.package_coverage.call_graph_success_rate < 0.8 ``` Identify projects not scanned in the last 7 days that still have outdated dependencies. ```bash theme={null} spec.last_scanned < now(-168h) and spec.dependency_counts.outdated > 0 ``` Find projects where dependency resolution is below 90%, which may indicate incomplete security analysis. ```bash theme={null} spec.package_coverage.success_rate < 0.9 ``` Identify projects with more than 100 total packages that also have a high number of critical vulnerabilities. ```bash theme={null} spec.package_coverage.total > 100 and spec.vulnerability_counts.total.critical > 20 ``` Find projects where more than 50 findings have been dismissed, useful for auditing triage quality. ```bash theme={null} spec.finding_counts.dismissed > 50 ``` Focus on npm projects with a high number of critical vulnerabilities. ```bash theme={null} spec.package_coverage.ecosystems contains ECOSYSTEM_NPM and spec.vulnerability_counts.total.critical > 10 ``` # Reports Source: https://docs.endorlabs.com/inventory-insights/reports/index Learn how to create analytics and findings reports for your organization. Reports allow you to export analytics and findings data from Endor Labs for offline review and analysis. You can generate the following reports: * **Analytics reports**: The analytics report provides a high-level view of vulnerability trends over time for the selected scope. It includes insights into newly discovered and resolved vulnerabilities, broken down by severity and tracked across defined time periods. The report also highlights remediation patterns, such as how long issues typically take to resolve, helping teams assess risk posture and remediation efficiency. Overall, it supports trend analysis, prioritization, and offline review of security metrics. * **Findings reports**: The findings report provides a detailed view of individual security findings identified within the selected scope. It includes information such as vulnerability details, severity, affected components, and contextual metadata to help teams understand risk and impact. The report also captures remediation-related context, such as fix availability, reachability, and policy signals, to support prioritization. Overall, it supports deep analysis, audits, and sharing actionable security findings for offline review. You can use reports to share security insights, support audits, and integrate results into external workflows. ## Create a report Create a report to view analytics or findings details for offline analysis. 1. Select **Reports** from the left sidebar. 2. Click **Create Report**. 3. Choose a report type. * **Analytics Report**: To export aggregated analytics data based on the selected filters. * **Findings Report**: To export detailed findings data based on the selected filters. 4. Choose the output format for the report. * Analytics reports are available in JSON format. * Findings reports are available in PDF. 5. Define which projects the report includes. If you don’t select any projects, the report includes all projects by default. * **Selected projects**: Includes only explicitly selected projects. * **Selected project tags**: Includes projects matching specific tags. 6. Choose the following filters to refine the data included in the report. * **Severity**: Filter the data based on finding severity such as Critical, High, Medium, or Low (labeled C, H, M, and L in the user interface). * **Category**: Filter the findings by category such as AI models, vulnerability, SCA, SAST, secrets, and container. * **Attributes**: Narrow down the list based on the following range of factors: * if a patch is available to fix the findings * if the vulnerable function is reachable * if the dependency is reachable * if the dependency originates from a current repository or a current tenant * if the dependency is a test dependency * if the dependency's discovery type is manifest, phantom, or segment match * if the finding originates from itself, direct, or a transitive dependency * filter the findings by the **Exploited** tag from **CISA KEV** * filter the findings by the **Warn** or **Break the Build** options set in the action policy. * **Time Period**: Restrict the report to findings or events within a selected range. Choose a preset such as **Last Day**, **Last Week**, **Last Month**, **Last 60 Days**, **Last 90 Days**, or **All Time**, or set a custom date range. 7. Click **Create Report** to generate your report. ## Manage reports You can track your report status and access report outputs after generating them. 1. Select **Reports** from the left sidebar to view the details of all the reports generated for your namespace. * **Report name**: The report type and creation timestamp. * **Report type**: Type of the report created such as Analytics Report or Findings Report. * **Created by**: The user who generated the report. * **Created date**: Date and time of report creation. * **Status indicator**: A green icon indicates successful generation. 2. Select a report to view additional details including the report scope and applied filters. 3. To download a report, click the three vertical dots and click **Download**. 4. To delete a report, click the three vertical dots and click **Delete**. # Export SBOMs and VEX Source: https://docs.endorlabs.com/inventory-insights/sbom/exporting-sboms/index Learn more about software transparency and the role of SBOMs in your organization. To export an SBOM you must first perform a successful `endorctl` scan. If you haven't successfully scanned a project see [quick start](/introduction/getting-started#quick-start) for more information. Endor Labs supports export in the [CycloneDX format](https://cyclonedx.org/docs/1.6/json/#bomFormat), [VEX](https://cyclonedx.org/capabilities/vex/) format, and [SPDX format](https://spdx.github.io/spdx-spec/v2.3/file-information/). ## Export an SBOM through the Endor Labs user interface When you export an SBOM at the project level, it includes all the packages in the project and all the package versions. This allows you to combine the SBOMs of multiple packages and versions into a single SBOM. A consolidated SBOM for the project enables quick identification and assessment of vulnerabilities across all software components. ### Export an SBOM as CycloneDX You can export SBOM of the project in the CycloneDX format. 1. Select **Projects** from the left sidebar. 2. Select the project for which to create an SBOM. 3. Click **Export SBOM** in the top right-hand corner. 4. Select **CycloneDX**. 5. Choose whether to export as an application or a library. If you choose to export as an application, enter an application name. 6. Select the output format and type of SBOM you would like to generate in **FILE FORMAT**. 7. Click **Add More** to select the packages and package versions you want to include in the SBOM. If you do not select specific packages, the SBOM will include information for all packages and package versions. Add more You can filter by ecosystem to select the type of packages to include in the SBOM. Add more ecosystem You can also search and select multiple package versions of the same package. Add more version 8. Select **Include test dependencies** to include test and other non-production dependencies in the exported SBOM or VEX file. By default, test dependencies are excluded from the export. 9. Click **Export SBOM**. A file containing the SBOM will download from your browser. ### Export an SBOM as SPDX You can export SBOM of the project in the SPDX format. 1. Select **Projects** from the left sidebar. 2. Select the project for which to create an SBOM. 3. Click **Export SBOM** in the top right-hand corner. 4. Select **SPDX**. 5. Enter the name of your application in **Application Name**. 6. Select the output format and type of SBOM you would like to generate in **File Format**. 7. Click **Add More** to select the packages and package versions you want to include in the SBOM. If you do not select specific packages, the SBOM will include information for all packages and package versions. Select packages You can filter by ecosystem to select the type of packages to include in the SBOM. Select packages You can also search and select multiple package versions of the same package. Select packages 8. Select **Include test dependencies** to include test and other non-production dependencies in the exported SBOM or VEX file. By default, test dependencies are excluded from the export. 9. Click **Export SBOM**. A file containing the SBOM will download from your browser. ## Export SBOM through endorctl You can use the following options with the SBOM export command. You can export an SBOM in CycloneDX or SPDX format using endorctl, for a single package version or across multiple package versions.
To export an SBOM you need the package version name for which you'd like to create an SBOM or its UUID. You can also export an SBOM with multiple package versions. To export an SBOM with multiple package versions, you need the package version UUIDs or the project name. Pass the package name or UUID to the command `endorctl sbom export` using the `--package-version-name` or `--uuid` flags. To export an SBOM, you must first retrieve the package version name through the API. You can easily export a reference package name and the scanned version you'd like to export as environment variables. ```shell theme={null} export PACKAGE_NAME= export VERSION= ``` Then query the API for the package version name and set this as an environment variable: ```shell theme={null} export PACKAGE_VERSION_NAME=$(endorctl api list -r PackageVersion --filter "meta.name matches $PACKAGE_NAME AND meta.name matches $VERSION" --field-mask=meta.name | jq -r ".list.objects[].meta.name") ``` Export an SBOM in the CycloneDX format through endorctl using the package version name. ```shell theme={null} endorctl sbom export --package-version-name=$PACKAGE_VERSION_NAME >> cyclonedx.json ``` Export an SBOM in the SPDX format through endorctl using the package version name. ```shell theme={null} endorctl sbom export --format spdx --package-version-name=$PACKAGE_VERSION_NAME >> spdx.json ```
To export multiple package versions in an SBOM, you need the UUIDs of package versions, or the name or UUID of the project to which the package versions belong. To create an SBOM based on project details, either provide the project UUID with the `--project-uuid` flag or the project name with the `--project-name` flag. You also need to provide a name for the package with the `--app-name` flag. Run the command to create an SBOM with multiple package versions using the project UUID. ```shell theme={null} endorctl sbom export -n --project-uuid= --app-name= >> .json ``` For example: ```shell theme={null} endorctl sbom export -n test --project-uuid=66e345c340669666c22979d6 --app-name=actions-hu/app-java-demo >> cyclonedx-sbom.json ``` Run the following commands to create an SBOM with multiple package versions with the project name. 1. Fetch the project name using the project's UUID. ```shell theme={null} endorctl api get -r Project --uuid -n |jq .meta.name ``` 2. Run the following command and replace `` with the project name you retrieved in the previous step. ```shell theme={null} endorctl sbom export -n --project-name= --app-name= >> .json ``` For example: ```shell theme={null} endorctl sbom export -n test --project-name=actions-hu/app-java-demo --app-name=actions-hu/app-java-demo >> cyclonedx-sbom.json ``` Generate an SBOM based on package version UUIDs, provide the package version UUIDs with the `--package-version-uuids` flag. You also need to provide a name for the package with the `--app-name` flag. ```shell theme={null} endorctl sbom export -n --package-version-uuids=,,... --app-name= >> .json ``` For example: ```shell theme={null} endorctl sbom export -n test --package-version-uuids=66e345c340669666c22979d6,89f456c340669666c229854a,43a56b1340669666c289d4a2 --app-name=actions-hu/app-java-demo >> spdx-sbom.json ```
To export multiple package versions in an SBOM, you need the UUIDs of package versions, or the name or UUID of the project to which the package versions belong. To create an SBOM based on project details, either provide the project UUID with the `--project-uuid` flag or the project name with the `--project-name` flag. You also need to provide a name for the package with the `--app-name` flag. Run the command to create an SBOM with multiple package versions using the project UUID. ```shell theme={null} endorctl sbom export --format spdx -n --project-uuid= --app-name= >> .json ``` For example: ```shell theme={null} endorctl sbom export --format spdx -n test --project-uuid=66e345c340669666c22979d6 --app-name=actions-hu/app-java-demo >> spdx-sbom.json ``` Run the following commands to create an SBOM with multiple package versions with the project name. 1. Fetch the project name using the project's UUID. ```shell theme={null} endorctl api get -r Project --uuid -n |jq .meta.name ``` 2. Run the following command and replace `` with the project name you retrieved in the previous step. ```shell theme={null} endorctl sbom export --format spdx --output-format= -n --project-name= --app-name= >> .json ``` For example: ```shell theme={null} endorctl sbom export --format spdx --output-format=json -n test --project-name=actions-hu/app-java-demo --app-name=actions-hu/app-java-demo >> spdx-sbom.json ``` Generate an SBOM based on package version UUIDs, provide the package version UUIDs with the `--package-version-uuids` flag. You also need to provide a name for the package with the `--app-name` flag. ```shell theme={null} endorctl sbom export --format spdx --output-format=json -n --package-version-uuids=,,... --app-name= >> .json ``` For example: ```shell theme={null} endorctl sbom export --format spdx --output-format=json -n test --package-version-uuids=66e345c340669666c22979d6,89f456c340669666c229854a,43a56b1340669666c289d4a2 --app-name=actions-hu/app-java-demo >> spdx-sbom.json ```
To export the CycloneDX SBOM as a library rather than an application use `--component-type=library`. ```shell theme={null} endorctl sbom export --component-type=library --package-version-name=$PACKAGE_VERSION_NAME >> cyclonedx.json ``` To export the CycloneDX SBOM in XML format rather than json use `--output-format` with the XML parameter. ```shell theme={null} endorctl sbom export --output-format=xml --package-version-name=$PACKAGE_VERSION_NAME >> cyclonedx.xml ``` To export a VEX document use the flag `--with-vex` ```shell theme={null} endorctl sbom export --with-vex ``` To export the SPDX SBOM using the tag-value format instead of json, use `--output-format=tag-value`. ```shell theme={null} endorctl sbom export --format spdx --output-format=tag-value --package-version-name=$PACKAGE_VERSION_NAME >> sbom-spdx.spdx ``` endorctl generates SBOMs in the CycloneDX format by default. ## Endor Labs Export Formats Endor Labs provides the following fields to map to the [NTIA minimum elements of an SBOM standard](https://www.ntia.gov/report/2021/minimum-elements-software-bill-materials-sbom). ### CycloneDX Format Endor Labs supports export in the CycloneDX format. The following table lists the mandatory and some optional fields in the SBOM file that Endor Labs exports. #### Patch data in SBOM CycloneDX SBOMs generated by Endor Labs include patch data for components that use an Endor patch. This allows consumers of the SBOM to see exactly which upstream version was patched, what changes were applied, and which vulnerabilities those patches resolve. The following fields describe how patch data appears in the exported SBOM. The following example shows a patched component in a CycloneDX SBOM. ```json expandable theme={null} { "bom-ref": "mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3-endor-2024-07-10", "type": "library", "name": "com.fasterxml.jackson.core:jackson-databind", "version": "2.9.10.3-endor-2024-07-10", "licenses": [], "purl": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.9.10.3-endor-2024-07-10", "pedigree": { "ancestors": [ { "bom-ref": "mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3", "type": "library", "name": "com.fasterxml.jackson.core:jackson-databind", "version": "2.9.10.3", "licenses": [], "purl": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.9.10.3", "externalReferences": [ { "url": "https://github.com/fasterxml/jackson-databind.git", "type": "vcs" } ] } ], "patches": [ { "diff": { "text": { "content": "", "contentType": "text/plain", "encoding": "base64" } }, "resolves": [ { "id": "", "name": "GHSA-q93h-jc49-78gg", "description": "", "type": "security" }, { "id": "", "name": "GHSA-p43x-xfjf-5jhr", "description": "", "type": "security" } ] } ] } } ``` ### VEX Format The following table lists the mandatory and some optional fields in the VEX file that Endor Labs exports. ### SPDX Format The following table lists the mandatory and some optional fields in the SPDX file that Endor Labs exports. # Import SBOMs Source: https://docs.endorlabs.com/inventory-insights/sbom/importing-sboms/index Learn more about software transparency and the role of importing SBOMs in your organization. SBOMs from vendors describe the components, licenses, and related metadata inside software you procure. Import them into Endor Labs so you can store, search, and analyze that composition next to the applications your organization builds. Endor Labs' SBOM Hub is a central location to store, search, and monitor SBOMs from vendors. When you import a file, Endor Labs ingests, parses, and analyzes it and keeps versions so you can see how vendor composition changes over time. For SBOM program design and day-to-day operations, see [Key questions for your SBOM program](https://www.endorlabs.com/blog/sbom-vex-security-program-operations). You can use [finding policies](/platform-administration/policies/finding-policies) to identify vulnerabilities, unmaintained open source software, license risks, and outdated dependencies in the SBOMs provided to you by your third-party software vendors. ## Import an SBOM to Endor Labs Import your project's SBOM into the Endor Labs application to discover vulnerabilities and view findings. You can use the following methods to import SBOMs: * [**Import SBOMs through the Endor Labs UI**](#import-sboms-through-the-endor-labs-ui) to upload your SBOMs and access vulnerability and dependency insights. * [**Import SBOMs through the Endor Labs CLI**](#import-sboms-through-the-endor-labs-cli) to ingest SBOMs and access vulnerability and dependency insights directly from your command line. ### Import SBOMs through the Endor Labs UI To import SBOMs through the Endor Labs UI and view vulnerability and dependency insights: 1. Select **SBOM Hub** from the left sidebar. 2. Select **Import SBOM** in the top right-hand corner. 3. Choose **Upload File** and select the type of SBOM you would like to upload, either in XML or json format. * Use **CycloneDX** if your vendor has provided you with a [CycloneDX format SBOM](https://cyclonedx.org/). * Use **SPDX** if your vendor has provided you with a [SPDX format SBOM](https://spdx.dev/). 4. Select **Browse** to upload your SBOM from your workstation or drag the SBOM into the Endor Labs user interface. Once you have imported your SBOM to Endor Labs, Endor Labs will schedule a scan in the background for the SBOM within the next few hours. ### Import SBOMs through the Endor Labs CLI Import an SBOM using the CLI to trigger an instant scan and immediately view vulnerabilities and dependency insights with the following command: ```bash theme={null} endorctl sbom import --sbom-file-path=/path/to/your/sbom.json ``` ```bash theme={null} endorctl sbom import --format=spdx --sbom-file-path=/path/to/your/sbom.json ``` See the [SBOM import command for endorctl](/developers-api/cli/commands/sbom/import) for more information. ## Manage SBOMs You can manage SBOMs by deleting unwanted files and editing tags for consistent search and filtering. ### Delete an SBOM 1. Select **SBOM Hub** from the left sidebar. 2. Select one or more SBOMs to remove. 3. Select the vertical three dots on the row, then select **Delete SBOM**. ### Edit tags for an SBOM Tags are keywords you attach to SBOMs to group and filter them, for example, by vendor or data classification. Tags can have a maximum of 63 characters and can contain letters A-Z, numbers (0-9), or any of (=@\_.-) special characters. To edit tags for SBOMs: 1. Select **SBOM Hub** from the left sidebar. 2. Select one or more SBOMs. 3. Click **Edit Tags** in the top right-hand corner. 4. Add, change, or remove tags, then save. #### Tagging strategies for SBOMs To improve your team's ability to search and manage SBOMs, you can tag them as they are received. Tagging SBOMs helps your team understand the applications, vendors, and their importance to your business. # SBOM Source: https://docs.endorlabs.com/inventory-insights/sbom/index Generate and manage Software Bill of Materials. A complete and accurate inventory of all first-party and third-party components is essential for risk identification. A Software Bill of Materials (SBOM) is a document that provides transparency into the software components of an application. SBOMs should ideally contain all direct and transitive components and the dependency relationships between them. They should also contain metadata associated with each of these components. ## For software producers Software producers—organizations that create and sell software—must provide software transparency through an SBOM to their customers on request. This reduces sales cycles, builds trust, and sometimes satisfies a regulatory or business requirement. A Vulnerability Exploitability eXchange (VEX) document conveys the potential risks associated with components that have known vulnerabilities within the specific context of the product. Software producers may need to, upon request, provide justification for known vulnerabilities and how they impact an application they sell. [Learn how to export SBOMs and VEX documents](/inventory-insights/sbom/exporting-sboms) for the software you test with Endor Labs. ## For software consumers Software consumers, or those who use software, need to understand their software inventory holistically. This includes both the software that they create and the software that they purchase. [Learn how to manage third-party risks](/inventory-insights/sbom/importing-sboms) with Endor Labs. ## Supported formats Endor Labs supports the following SBOM formats: * **CycloneDX**: A lightweight SBOM standard designed for use in application security contexts * **SPDX**: An open standard for communicating software bill of material information # Scan history Source: https://docs.endorlabs.com/inventory-insights/scan-history/index View the history of scans performed on a project. Scan history provides a detailed overview of past security scans performed on a project. It helps you understand your project's security posture over time. With full context and details about individual scans in their repositories, you can assess scan fidelity and troubleshoot issues. 1. Select **Projects** from the left sidebar. 2. Search for and select a project to review. 3. Select **Scan history** to review the past scans. * **List of Scans**: View all past scans, including details such as the scan time, duration, scan type, and tags. * **Findings Summary**: Review the number of security findings, categorized by severity: Critical, High, Medium, or Low. * **Commit Details**: Each scan is linked to a specific commit SHA, allowing users to track security issues to specific code changes. * **Scanned By**: Identifies the user or system that initiated the scan. * **Filtering & Search**: You can filter scans by status, scan type, and time range. You can search by tags, commit SHA, or specific include or exclude file paths. For example, you can select **Container** as a scan type from the dropdown list. Scan history Scan types like **analytics**, **analytics-check**, and **finding-refresh** are automated and system-triggered. They appear in scan history but do not require any user action. See [Scan types](/scan) for more information. 4. Select a record to view general information about the scan or its logs. * **Overview**: View general information about the scan, including the scan status, result UUID, detected programming languages, system details, and the versions of key development tools used in the environment. * **Issues**: View additional errors and warnings from the scan. This section appears only when the scan reports errors or warnings. Scan history issues * **Logs**: Monitor scan logs, even while scans are running, and filter by severity level, with selectable log severity from Emergency, Alert, Critical, Error, Warning, Notice, Info, or Debug for in-depth debugging and policy evaluations. You can access scan logs and toolchain details for projects onboarded through Endor Labs cloud using the GitHub, GitLab, or Azure DevOps Apps. The log levels in the selected scan result determine the available log severities. For SAST and secret findings, logs include the file path and line numbers where the issue was detected. Scan history logs * **Resolved Findings**: View findings that are resolved in a particular scan. This section appears only when the scan resolves one or more findings. Each entry shows the finding name, severity, category, first detected time, and attribute tags. You can also copy the finding UUID. Scan history resolved findings # Configure the Package Firewall with direct integration Source: https://docs.endorlabs.com/package-firewall/direct-integration/index Beta
Configure a direct integration to route package installation requests through the Package Firewall without relying on an intermediary registry. Direct integration routes package installation requests from your package managers through the Package Firewall directly, without an intermediary registry such as JFrog Artifactory or Google Artifact Registry. The Package Firewall evaluates each package request based on the malware check and the configured [Package Firewall policy](/package-firewall/policy) conditions, and handles each request in one of three ways: * Block the installation and return an `HTTP 403` when the package is in the Endor Labs malware database, or a policy condition matches **Block**. The developer sees a generic `403` response without the specific reason. The Package Firewall records a log with the package, version, and reason. * Allow the installation if a policy condition matches with **Warn**. The Package Firewall records a warning log with the package, version, and reason. * Allow the installation if no malware is detected. No log is recorded. The Package Firewall records one of the following reasons in the log when it blocks a package: * `malware detected for package @`: Endor Labs classified the package as malware. * `package has a CVSS vulnerability at or above the configured severity threshold`: The package has a known vulnerability at or above the CVSS severity threshold set in your policy. Endor Labs uses CVSS 3.x by default and evaluates vulnerability severity using that version. You can change the CVSS version for your namespace in [system settings](/platform-administration/configure-system-settings/#configure-cvss-score-version). * `package license is restricted`: The license violates your Package Firewall policy. * `package does not meet min_age_hours requirement`: The package is newer than the minimum age set in your policy. Configure the direct integration for Package Firewall if your organization does not use a private registry such as JFrog Artifactory or Google Artifact Registry. IT administrators can use Mobile Device Management (MDM) scripts to deploy Package Firewall configurations to developer machines, eliminating the need for manual setup on each machine. These scripts update package manager configuration files with the Package Firewall URL and credentials. They also encode a `@` label into those credentials, so the firewall attributes every request to a developer and machine instead of the shared API key. See [User attribution](/package-firewall/mdm-deployment#user-attribution) to learn how the label works. The Package Firewall logs show the attributed user on each event, so you can identify who requested a warned or blocked package. See [View Package Firewall logs](/package-firewall/logs) to learn more. ## Package Firewall support matrix The following table outlines the package managers and ecosystems the Package Firewall supports through direct integration. ## Configure the Package Firewall Complete the following steps to configure direct integration with the Package Firewall: 1. [Create an API key for the Package Firewall](#create-an-api-key-for-the-package-firewall). 2. [Configure your package manager configuration file](#configure-your-package-manager-configuration-file). 3. [Verify your setup](#verify-your-setup). ### Create an API key for the Package Firewall Create an API key dedicated to the Package Firewall so that can authenticate to it. You can create it through one of the following methods: * Using the Endor Labs user interface, with the **Package Firewall User** role. See [API keys](/platform-administration/api-keys#create-an-api-key-through-the-endor-labs-user-interface) to learn more. * Using endorctl, with the `SYSTEM_ROLE_PACKAGE_FIREWALL` role. Make sure to [install and configure endorctl](/developers-api/cli/install-and-configure) before you create the key. To create the key using endorctl, run the following command and replace: * `` with your namespace. * `` with the name of the API key for the Package Firewall use case. * `` with the API key expiration in ISO 8601 UTC format, for example `2026-12-31T23:59:59Z`. ```bash theme={null} export NAMESPACE="" export KEY_NAME="" endorctl api create -r APIKey -n "$NAMESPACE" --data '{ "meta": { "name": "'"$KEY_NAME"'" }, "spec": { "permissions": { "roles": ["SYSTEM_ROLE_PACKAGE_FIREWALL"] }, "expiration_time": "" }, "propagate": true }' ``` From the response, save the following values in a secure location. Use them as your Package Firewall credentials when you configure your package manager configuration file. * **API key:** `spec.key` * **API secret:** `spec.secret` ### Configure your package manager configuration file Configure your package manager configuration file with the Package Firewall URL, your API key as the username, and your API secret as the password. The Package Firewall authenticates installation requests by validating the username and password pair. Replace `` and `` with the credentials you saved in the previous step. ### Verify your setup To verify your setup, install a package that Endor Labs has classified as malware. The Package Firewall should block the installation and return an `HTTP 403`. The following examples show the test command for each package manager. Run the following command to test the Package Firewall with npm. ```bash theme={null} npm install endor-firewall-test@1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `403 Forbidden` response confirms that the firewall blocked the package. ```bash theme={null} npm error 403 403 Forbidden - GET https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz - Forbidden npm error 403 In most cases, you or one of your dependencies are requesting a package version that is forbidden by your security policy, or on a server you do not have access to. npm error A complete log of this run can be found in: /Users/johndoe/.npm/_logs/2026-06-04T15_04_29_131Z-debug-0.log ``` Run the following command to test the Package Firewall with pnpm. ```bash theme={null} pnpm add endor-firewall-test@1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `Forbidden - 403` response confirms that the firewall blocked the package. ```bash theme={null} Packages: +1 + [ERR_PNPM_FETCH_403] GET https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz: Forbidden - 403 This error happened while installing a direct dependency of /Users/local-dev/Code/sample-projecr //factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/:_auth=ZW5k[hidden] //factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/:_username=xxxxx //factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/:_password=[hidden] Progress: resolved 1, reused 0, downloaded 0, added 0 ``` Run the following command to test the Package Firewall with Yarn Classic. ```bash theme={null} yarn add endor-firewall-test@1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `Forbidden - 403` response confirms that the firewall blocked the package. ```bash theme={null} yarn add v1.22.22 info No lockfile found. [1/4] 🔍 Resolving packages... [2/4] 🚚 Fetching packages... error Error: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz: Request failed "403 Forbidden" at ResponseError.ExtendableBuiltin (/Users/johndoe/.nvm/versions/node/v24.6.0/lib/node_modules/yarn/lib/cli.js:696:66) at new ResponseError (/Users/johndoe/.nvm/versions/node/v24.6.0/lib/node_modules/yarn/lib/cli.js:802:124) at Request. (/Users/johndoe/.nvm/versions/node/v24.6.0/lib/node_modules/yarn/lib/cli.js:66750:16) at Request.emit (node:events:508:28) at module.exports.Request.onRequestResponse (/Users/johndoe/.nvm/versions/node/v24.6.0/lib/node_modules/yarn/lib/cli.js:142287:10) at ClientRequest.emit (node:events:508:28) at HTTPParser.parserOnIncomingClient (node:_http_client:772:27) at HTTPParser.parserOnHeadersComplete (node:_http_common:117:17) at TLSSocket.socketOnData (node:_http_client:614:22) at TLSSocket.emit (node:events:508:28) info Visit https://yarnpkg.com/en/docs/cli/add for documentation about this command. ``` Run the following command to test the Package Firewall with Yarn Berry. ```bash theme={null} yarn add endor-firewall-test@1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `403 (Forbidden)` response confirms that the firewall blocked the package. ```bash theme={null} ➤ YN0000: · Yarn 4.16.0 ➤ YN0000: ┌ Resolution step ➤ YN0085: │ + endor-firewall-test@npm:1.0.0 ➤ YN0000: └ Completed ➤ YN0000: ┌ Fetch step ➤ YN0035: │ endor-firewall-test@npm:1.0.0: The remote server failed to provide the requested resource ➤ YN0035: │ Response Code: 403 (Forbidden) ➤ YN0035: │ Request Method: GET ➤ YN0035: │ Request URL: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz ➤ YN0000: └ Completed in 0s 839ms ➤ YN0000: · Failed with errors in 0s 853ms ``` Run the following command to test the Package Firewall with Bun. ```bash theme={null} bun add endor-firewall-test@1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `403` response confirms that the firewall blocked the package. ```bash theme={null} bun add v1.3.14 (0d9b296a) error: GET https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz - 403 ``` Run the following command to test the Package Firewall with pip. ```bash theme={null} pip install endor-firewall-test==1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `403` response confirms that the firewall blocked the package. ```bash theme={null} Looking in indexes: https://@factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/simple/ Collecting endor_firewall_test==1.0.0 ERROR: HTTP error 403 while getting: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata ERROR: 403 Client Error: Forbidden for URL: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata ``` Run the following command to test the Package Firewall with uv. ```bash theme={null} uv pip install endor-firewall-test==1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `(403 Forbidden)` response confirms that the firewall blocked the package. ```bash theme={null} error: Failed to fetch: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata Caused by: HTTP status client error (403 Forbidden) for URL: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata ``` Run the following command to test the Package Firewall with Poetry. ```bash theme={null} poetry add endor-firewall-test==1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `403 Forbidden` response confirms that the firewall blocked the package. ```bash theme={null} Updating dependencies Resolving dependencies... (0.8s) Source (endor-firewall): Failed to retrieve metadata at: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata Resolving dependencies... (2.8s) Source (endor-firewall): Failed to retrieve metadata at: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata Resolving dependencies... (3.9s) Source (endor-firewall): Failed to retrieve metadata at: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata Resolving dependencies... (4.2s) 403 Client Error: Forbidden for URL: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl ``` Run the following command to test the Package Firewall with Go. ```bash theme={null} go install github.com/endorlabstest/endor-firewall-test@v1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `403 Forbidden` response confirms that the firewall blocked the package. ```bash theme={null} go: github.com/endorlabstest/endor-firewall-test@v1.0.0: reading https://@factory.endorlabs.com/v1/namespaces/johndoe/firewall/go/github.com/endorlabstest/endor-firewall-test/@v/v1.0.0.info: 403 Forbidden ``` Add `io.github.endorlabs:endor-java-webapp-demo:4.1` as a dependency in your `pom.xml`, then run one of the following commands to test the Package Firewall with Maven. For a project-level `settings.xml` in your project directory, pass it explicitly with `-s`: ```bash theme={null} mvn dependency:resolve -s settings.xml ``` For a global `settings.xml` at `${mvn_home}/conf/settings.xml`, Maven picks it up automatically: ```bash theme={null} mvn dependency:resolve ``` When the Package Firewall blocks the package, the output looks similar to the following. The `Forbidden (403)` response confirms that the firewall blocked the package. ```bash theme={null} [INFO] Scanning for projects... [INFO] [INFO] -----------------------< com.example:my-app >------------------------ [INFO] Building my-app 1.0.0 [INFO] from pom.xml [INFO] --------------------------------[ jar ]--------------------------------- Downloading from endor-firewall: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/maven/io/github/endorlabs/endor-java-webapp-demo/4.1/endor-java-webapp-demo-4.1.pom [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1.600 s [INFO] Finished at: 2026-06-09T19:37:32+05:30 [INFO] ------------------------------------------------------------------------ [ERROR] Failed to execute goal on project my-app: Could not collect dependencies for project com.example:my-app:jar:1.0.0 [ERROR] Failed to read artifact descriptor for io.github.endorlabs:endor-java-webapp-demo:jar:4.1 [ERROR] Caused by: The following artifacts could not be resolved: io.github.endorlabs:endor-java-webapp-demo:pom:4.1 (absent): Could not transfer artifact io.github.endorlabs:endor-java-webapp-demo:pom:4.1 from/to endor-firewall (https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/maven): status code: 403, reason phrase: Forbidden (403) [ERROR] ``` ### Configure uv for CI/CD When you run `uv lock` with the Package Firewall configured, uv writes the Firewall URL, including your namespace, into `uv.lock`. Every package resolves through Endor Labs instead of a canonical PyPI source. Since the lockfile references authenticated Firewall URLs, reproducible installs fail in CI/CD when [credentials](#create-an-api-key-for-the-package-firewall) to `factory.endorlabs.com` are absent. uv commands that require a connection to the lockfile URLs, such as `uv sync --locked` or `uv sync --frozen`, return `401 Unauthorized` unless credentials are provided. To install from the lockfile in CI/CD without committing credentials to your repository, give your index a name and pass the credentials as environment variables. 1. In your existing uv index in` pyproject.toml` or `uv.toml`, add a name and remove the credentials from the URL. uv matches credentials to an index by this name. ```toml theme={null} [[tool.uv.index]] name = "endor-firewall" url = "https://factory.endorlabs.com/v1/namespaces//firewall/pypi/simple/" default = true ``` ```toml theme={null} [[index]] name = "endor-firewall" url = "https://factory.endorlabs.com/v1/namespaces//firewall/pypi/simple/" default = true ``` 2. Set the credentials as environment variables in your CI/CD environment. uv derives the variable names from the index name in uppercase, so `endor-firewall` becomes `ENDOR_FIREWALL`. Use your Package Firewall API key as the username and your API secret as the password. For more information, refer to the [uv environment variable reference](https://docs.astral.sh/uv/reference/environment/#uv_index_name_password). ```bash theme={null} export UV_INDEX_ENDOR_FIREWALL_USERNAME= export UV_INDEX_ENDOR_FIREWALL_PASSWORD= ``` ## Next steps * Configure which packages the firewall flags and how it responds. See [Package Firewall policy](/package-firewall/policy) to learn more. * Review the events the firewall records. See [View Package Firewall logs](/package-firewall/logs) to learn more. ## Troubleshooting and FAQ The variables aren't in your current shell scope. On Windows, set them with `[System.Environment]::SetEnvironmentVariable` using the `User` scope, then restart your terminal. For a single session, you can set `$env:POETRY_HTTP_BASIC_ENDOR_FIREWALL_USERNAME` and `$env:POETRY_HTTP_BASIC_ENDOR_FIREWALL_PASSWORD` in PowerShell instead. # Configure the Package Firewall with Google Artifact Registry Source: https://docs.endorlabs.com/package-firewall/google-artifact-registry/index Route package installation requests through the Package Firewall by configuring Google Artifact Registry remote repositories. Configure Google Artifact Registry to use the Package Firewall URL as the upstream source for a remote repository instead of the public package registries. Every package installation request flows through Endor Labs, so the Package Firewall can block known malicious packages before they reach your environment. The Package Firewall evaluates each package request based on the malware check and the configured [Package Firewall policy](/package-firewall/policy) conditions, and handles each request in one of three ways: * Block the installation and Google Artifact Registry returns `HTTP 403` if the package is found in the Endor Labs malware database, or if a policy condition matches with **Block**. The Package Firewall records a log with the package, version, and reason. * Allow the installation if a policy condition matches with **Warn**. The Package Firewall records a warning log with the package, version, and reason. * Allow the installation if the package passes all checks. No log is recorded. Google Artifact Registry returns a generic `HTTP 403` when it blocks a request without surfacing the specific reason. To see why a package was blocked, review the [Package Firewall logs](/package-firewall/logs). ## Required Google Cloud permissions Ensure that you have the following roles in the Google Cloud project that hosts Artifact Registry: * [Artifact Registry Administrator](https://cloud.google.com/artifact-registry/docs/access-control) to create remote repositories. * [Secret Manager Admin](https://cloud.google.com/secret-manager/docs/access-control) to create the secret and grant Artifact Registry access to it. * [Service Usage Admin](https://cloud.google.com/service-usage/docs/access-control) to enable the Secret Manager API. A project **Owner** or **Editor** role covers all of these. ## Configure the Package Firewall Complete the following steps to integrate Google Artifact Registry with the Endor Labs Package Firewall: 1. [Create an API key for the Package Firewall](#create-an-api-key-for-the-package-firewall). 2. [Store the API secret in Secret Manager](#store-the-api-secret-in-secret-manager). 3. [Configure Google Artifact Registry](#configure-google-artifact-registry). 4. [Set up local package managers](#set-up-local-package-managers). 5. [Verify your setup](#verify-your-setup). ### Create an API key for the Package Firewall Create an API key dedicated to the Package Firewall so that can authenticate to it. You can create it through one of the following methods: * Using the Endor Labs user interface, with the **Package Firewall User** role. See [API keys](/platform-administration/api-keys#create-an-api-key-through-the-endor-labs-user-interface) to learn more. * Using endorctl, with the `SYSTEM_ROLE_PACKAGE_FIREWALL` role. Make sure to [install and configure endorctl](/developers-api/cli/install-and-configure) before you create the key. To create the key using endorctl, run the following command and replace: * `` with your namespace. * `` with the name of the API key for the Package Firewall use case. * `` with the API key expiration in ISO 8601 UTC format, for example `2026-12-31T23:59:59Z`. ```bash theme={null} export NAMESPACE="" export KEY_NAME="" endorctl api create -r APIKey -n "$NAMESPACE" --data '{ "meta": { "name": "'"$KEY_NAME"'" }, "spec": { "permissions": { "roles": ["SYSTEM_ROLE_PACKAGE_FIREWALL"] }, "expiration_time": "" }, "propagate": true }' ``` From the response, save the following values in a secure location. * **API key:** `spec.key` * **API secret:** `spec.secret` ### Store the API secret in Secret Manager Google Artifact Registry reads the upstream password from Secret Manager, so you must store your API secret there before you configure the remote repository. 1. Sign in to the [Google Cloud console](https://console.cloud.google.com) and select your project. 2. Search for and select **Secret Manager API**. 3. Click **Enable**. If you see **Manage** instead, the API is already enabled. 4. Search for and select **Secret Manager**. 5. Create a secret with a name, such as `endor-pkg-firewall-secret`, and set the **Secret value** to your API secret. Refer to [Google Cloud documentation](https://cloud.google.com/secret-manager/docs/create-secret-quickstart#create_a_secret_and_access_a_secret_version) to learn how to create a secret. ### Configure Google Artifact Registry Configure a remote repository in Google Artifact Registry for each package type you want to route through the Package Firewall. A remote repository proxies an upstream source, so you set the Package Firewall URL as the custom upstream. Provide your API key as the username and the Secret Manager secret as the password. The remaining repository settings, such as location and cleanup policies, are specific to Google Artifact Registry. Configure them based on your requirements. Google Artifact Registry does not support custom upstream URL for Go remote repositories, so you cannot route Go modules through the Package Firewall with this integration. To route Go modules through the Package Firewall, use [JFrog Artifactory](/package-firewall/jfrog-artifactory) or [direct integration](/package-firewall/direct-integration). 1. In the Google Cloud console, go to **Artifact Registry** > **Repositories**. 2. Click **Create Repository**. 3. Enter a repository name, such as `endor-npm-repository`. 4. Choose **npm** as the **Format**. 5. Choose **Custom** in **Remote repository source**. 6. Enter `https://factory.endorlabs.com/v1/namespaces//firewall/npm` as the custom repository URL. Replace `` with your Endor Labs namespace. 7. Choose **Authenticated** in **Remote repository authentication mode**. 8. Enter your API key (`spec.key`) as the **Username for the upstream repository**. 9. Under **Store your credentials in Secret Manager**, select the **Secret** you created. 10. Under **Location type**, choose **Region** or **Multi-Region** and select a location. Refer to [Repository locations](https://cloud.google.com/artifact-registry/docs/repositories/repository-locations) for details. 11. Click **Create**. 1. In the Google Cloud console, go to **Artifact Registry** > **Repositories**. 2. Click **Create Repository**. 3. Enter a repository name, such as `endor-pypi-repository`. 4. Choose **Python** as the **Format**. 5. Choose **Custom** in **Remote repository source**. 6. Enter `https://factory.endorlabs.com/v1/namespaces//firewall/pypi` as the custom repository URL. Replace `` with your Endor Labs namespace. 7. Choose **Authenticated** in **Remote repository authentication mode**. 8. Enter your API key (`spec.key`) as the **Username for the upstream repository**. 9. Under **Store your credentials in Secret Manager**, select the **Secret** you created. 10. Under **Location type**, choose **Region** or **Multi-Region** and select a location. Refer to [Repository locations](https://cloud.google.com/artifact-registry/docs/repositories/repository-locations) for details. 11. Click **Create**. 1. In the Google Cloud console, go to **Artifact Registry** > **Repositories**. 2. Click **Create Repository**. 3. Enter a repository name, such as `endor-maven-repository`. 4. Choose **Maven** as the **Format**. 5. Choose **Custom** in **Remote repository source**. 6. Enter `https://factory.endorlabs.com/v1/namespaces//firewall/maven` as the custom repository URL. Replace `` with your Endor Labs namespace. 7. Choose **Authenticated** in **Remote repository authentication mode**. 8. Enter your API key (`spec.key`) as the **Username for the upstream repository**. 9. Under **Store your credentials in Secret Manager**, select the **Secret** you created. 10. Under **Location type**, choose **Region** or **Multi-Region** and select a location. Refer to [Repository locations](https://cloud.google.com/artifact-registry/docs/repositories/repository-locations) for details. 11. Click **Create**. ### Set up local package managers Configure your local package managers to use the Google Artifact Registry repository as their source, and authenticate with your Google Cloud credentials. Refer to Google's documentation for [npm](https://docs.cloud.google.com/artifact-registry/docs/nodejs/authentication), [Python](https://docs.cloud.google.com/artifact-registry/docs/python/authentication), and [Maven](https://docs.cloud.google.com/artifact-registry/docs/java/authentication). ### Verify your setup To verify your setup, install a package that Endor Labs has classified as malware. The Package Firewall should block the installation and return an `HTTP 403`. The following are examples of packages classified as malware by Endor Labs. Run the following command to test the Package Firewall with npm. ```bash theme={null} npm install endor-firewall-test ``` When the Package Firewall blocks the package, the output looks similar to the following. The `E403` error code and `403 Forbidden` response confirm that the firewall blocked the package. ```bash theme={null} npm error code E403 npm error 403 403 Forbidden - GET https://us-central1-npm.pkg.dev/johndoe-project/johndoe-npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz - 403 Forbidden error returned by the external repository... this typically means your upstream credentials are invalid; url="https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz" npm error 403 In most cases, you or one of your dependencies are requesting npm error 403 a package version that is forbidden by your security policy, or npm error 403 on a server you do not have access to. ``` Run the following command to test the Package Firewall with PyPI. ```bash theme={null} pip install endor-firewall-test ``` When the Package Firewall blocks the package, the output looks similar to the following. The `403` response confirms that the firewall blocked the package. ```bash theme={null} Looking in indexes: https://pypi.org/simple, https://oauth2accesstoken:****@us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/simple/ Collecting endor-firewall-test ERROR: HTTP error 403 while getting https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/endor-firewall-test/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 (from https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/simple/endor-firewall-test/) (requires-python:>=3.7) ERROR: Could not install requirement endor-firewall-test from https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/endor-firewall-test/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 because of HTTP error 403 Client Error: Forbidden for url: https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/endor-firewall-test/endor_firewall_test-1.0.0-py3-none-any.whl for URL https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/endor-firewall-test/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 (from https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/simple/endor-firewall-test/) (requires-python:>=3.7) ``` Add `io.github.endorlabs:endor-java-webapp-demo:4.1` as a dependency in your `pom.xml`, then run the following command to test the Package Firewall with Maven. ```bash theme={null} mvn dependency:resolve -s settings.xml ``` When the Package Firewall blocks the package, the output looks similar to the following. The `403 Forbidden` response confirms that the firewall blocked the package. ```bash theme={null} Downloading from endor-firewall-gar: https://us-central1-maven.pkg.dev/johndoe-project/johndoe-maven/io/github/endorlabs/endor-java-webapp-demo/4.1/endor-java-webapp-demo-4.1.pom [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE [INFO] ------------------------------------------------------------------------ [ERROR] Failed to execute goal on project endor-firewall-maven-test: Could not resolve dependencies for project com.example:endor-firewall-maven-test:jar:1.0.0: Failed to collect dependencies at io.github.endorlabs:endor-java-webapp-demo:jar:4.1: Failed to read artifact descriptor for io.github.endorlabs:endor-java-webapp-demo:jar:4.1: Could not transfer artifact io.github.endorlabs:endor-java-webapp-demo:pom:4.1 from/to endor-firewall-gar (https://us-central1-maven.pkg.dev/johndoe-project/johndoe-maven): authorization failed for https://us-central1-maven.pkg.dev/johndoe-project/johndoe-maven/io/github/endorlabs/endor-java-webapp-demo/4.1/endor-java-webapp-demo-4.1.pom, status: 403 Forbidden -> [Help 1] ``` After you confirm that the Package Firewall blocks malware, you can view the recorded events. See [View Package Firewall logs](/package-firewall/logs) to learn more. ## Troubleshooting and FAQ Google Artifact Registry validates the upstream URL and credentials when you create a remote repository, and creates it only if the test passes. If it fails, check that the custom repository URL, upstream username, and Secret Manager secret are correct. To skip the check, select **Disable upstream validation** on the form. If Endor Labs flags a package as malware after Google Artifact Registry cached it, Google Artifact Registry continues to serve it until the cache expires. Use a short cache duration to reduce that window. * Verify that the Package Firewall URL set as the custom upstream is correct. * Ensure network connectivity from Google Artifact Registry to the Package Firewall. * Ensure the firewall rules allow outbound connections from Google Artifact Registry. * Verify the API key and secret are correct and that the key has the **Package Firewall User** role. * Verify that the Secret Manager secret holds the API secret and that the repository can access it. * Set cache expiration to short durations so that more requests hit the Package Firewall. * Check the cache hit and miss rates. Clear the cache if you need to test with a fresh request. # Package Firewall Source: https://docs.endorlabs.com/package-firewall/index Block known malicious packages and control package installations in real time with Endor Labs Package Firewall. Package Firewall offers real-time protection against malicious packages during software installations. It safeguards your software supply chain by preventing malicious packages from reaching your developers. Positioned between package managers and public package registries, it blocks the installation of known malicious packages by default while allowing safe packages to install normally. Security teams often discover malware only after it enters your environment, forcing reactive cleanup. Package Firewall closes this gap by intercepting every package installation request before it completes. It blocks any malicious package instantly and returns an error, so the package never reaches your environment. Legitimate packages pass through unchanged, keeping your developers productive and your pipeline secure. Package Firewall checks every package in the dependency tree individually, including transitive dependencies. If it flags any dependency, the installation is blocked. Configured policies apply to transitive dependencies as well. See [How it works](#how-it-works) for more details. ## Get started Choose the integration that fits your environment: [JFrog Artifactory](/package-firewall/jfrog-artifactory), [Google Artifact Registry](/package-firewall/google-artifact-registry), [direct integration](/package-firewall/direct-integration), or [deploy to developer machines with MDM](/package-firewall/mdm-deployment). Define how the firewall responds to flagged packages: block, warn, or allow safe versions on malware and minimum package age, block or warn on vulnerabilities and restricted licenses, and set exceptions. You can also send Slack notifications when a package installation is blocked or warned. See [Package Firewall policy](/package-firewall/policy). Confirm the firewall blocks malware and review every recorded event. See [View Package Firewall logs](/package-firewall/logs). ## Supported ecosystems The Package Firewall supports the following registries and any package manager that uses them. Google Artifact Registry does not support custom upstream URL for Go remote repositories, so you cannot route Go modules through the Package Firewall with this integration. To route Go modules through the Package Firewall, use [JFrog Artifactory](/package-firewall/jfrog-artifactory) or [direct integration](/package-firewall/direct-integration). ## How it works Package Firewall inspects each package request before the package is downloaded. When a developer or CI pipeline requests a package, the request routes through the firewall, either directly or through a private registry such as JFrog Artifactory or Google Artifact Registry. 1. **Route traffic through Package Firewall**: Your package manager or private registry forwards each request to the firewall so that it evaluates every package before the download completes. 2. **Authenticate and control access**: Package Firewall verifies that each request presents an Endor Labs API key with the Package Firewall User role. 3. **Evaluate each package request**: For each request, Package Firewall parses the ecosystem, package name, and version, and checks it against the Endor Labs malware database. If you configure a [Package Firewall policy](/package-firewall/policy), the firewall also evaluates vulnerabilities, restricted licenses, and minimum package age. You can define exceptions that let specific packages bypass all checks, so critical builds and workflows continue uninterrupted. 4. **Take action**: Based on the malware check and policy conditions, Package Firewall takes the configured action on the request and records an event with the package, version, and reason. You can set each condition (malware, vulnerabilities, restricted licenses, and minimum package age) to one of the following responses: * **Warn**: Records the event and allows the package installation without interrupting your CI pipeline. * **Block**: Prevents the package installation entirely and returns an error. * **Allow safe versions only (curate)**: Removes the unsafe versions from the response so the package manager installs a safe version instead. Available for the malware and minimum package age conditions on the npm and PyPI ecosystems. See [Allow safe versions](/package-firewall/policy#allow-safe-versions) to learn more. When a package passes all checks, the installation proceeds and no log is recorded. 5. **Record events in Package Firewall logs**: Package Firewall records the actions the firewall takes on package installation requests, which is helpful for debugging and compliance. The logs include details such as the package, version, time of the event, and the reason the firewall flagged the package. See [View Package Firewall logs](/package-firewall/logs) for more details. # Configure the Package Firewall with JFrog Artifactory Source: https://docs.endorlabs.com/package-firewall/jfrog-artifactory/index Route package installation requests through the Package Firewall by configuring JFrog Artifactory remote repositories. Configure JFrog Artifactory to use the Package Firewall URL as its remote source instead of upstream package registries. Every package installation request flows through Endor Labs, so the Package Firewall can block known malicious packages before they reach your environment. The Package Firewall evaluates each package request based on the malware check and the configured [Package Firewall policy](/package-firewall/policy) conditions, and handles each request in one of three ways: * Block the installation and Artifactory returns `HTTP 404` if the package is found in the Endor Labs malware database, or if a policy condition matches with **Block**. The Package Firewall records a log with the package, version, and reason. * Allow the installation if a policy condition matches with **Warn**. The Package Firewall records a warning log with the package, version, and reason. * Allow the installation if the package passes all checks. No log is recorded. Artifactory returns a generic `HTTP 404` when it blocks a request without surfacing the specific reason. To see why a package was blocked, review the [Package Firewall logs](/package-firewall/logs). **JFrog Artifactory requirement** You must have a JFrog Artifactory instance with permission to create remote repositories and configure credentials. ## Configure the Package Firewall Complete the following steps to integrate JFrog Artifactory with the Endor Labs Package Firewall: 1. [Create an API key for the Package Firewall](#create-an-api-key-for-the-package-firewall). 2. [Configure JFrog Artifactory](#configure-jfrog-artifactory). 3. [Local setup for developers](#local-setup-for-developers). 4. [Verify your setup](#verify-your-setup). ### Create an API key for the Package Firewall Create an API key dedicated to the Package Firewall so that can authenticate to it. You can create it through one of the following methods: * Using the Endor Labs user interface, with the **Package Firewall User** role. See [API keys](/platform-administration/api-keys#create-an-api-key-through-the-endor-labs-user-interface) to learn more. * Using endorctl, with the `SYSTEM_ROLE_PACKAGE_FIREWALL` role. Make sure to [install and configure endorctl](/developers-api/cli/install-and-configure) before you create the key. To create the key using endorctl, run the following command and replace: * `` with your namespace. * `` with the name of the API key for the Package Firewall use case. * `` with the API key expiration in ISO 8601 UTC format, for example `2026-12-31T23:59:59Z`. ```bash theme={null} export NAMESPACE="" export KEY_NAME="" endorctl api create -r APIKey -n "$NAMESPACE" --data '{ "meta": { "name": "'"$KEY_NAME"'" }, "spec": { "permissions": { "roles": ["SYSTEM_ROLE_PACKAGE_FIREWALL"] }, "expiration_time": "" }, "propagate": true }' ``` From the response, save the following values in a secure location. Use them as your Package Firewall credentials when you configure the JFrog Artifactory remote repository. * **API key:** `spec.key` * **API secret:** `spec.secret` ### Configure JFrog Artifactory Configure a remote repository in JFrog Artifactory for each package type you want to route through the Package Firewall. Use the steps below for npm, PyPI, or Go packages. 1. [Log in to JFrog Artifactory](https://my.jfrog.com/login/). 2. Select **Administration** > **Repositories** from the left sidebar. 3. Click **Create a Repository** and select **Remote**. 4. Select **npm** as the package type. 5. Enter a **Repository Key**, for example `endor-firewall-npm`. 6. Enter the repository URL: `https://factory.endorlabs.com/v1/namespaces//firewall/npm/`. Replace `` with your Endor Labs namespace. 7. Enter the **User Name** and **Password** you saved when creating the API key. 8. Click **Create Remote Repository**. Configure npm 1. [Log in to JFrog Artifactory](https://my.jfrog.com/login/). 2. Select **Administration** > **Repositories** from the left sidebar. 3. Click **Create a Repository** and select **Remote**. 4. Select **PyPI** as the package type. 5. Enter a **Repository Key**, for example `endor-firewall-pypi`. 6. Enter the repository URL: `https://factory.endorlabs.com/v1/namespaces//firewall/pypi/`. Replace `` with your Endor Labs namespace. 7. Enter the **User Name** and **Password** you saved when creating the API key. 8. In **PyPI Settings**, set **Registry URL** to the same URL you entered in step 6. 9. Click **Create Remote Repository**. Configure PyPI The Package Firewall uses a virtual repository URL that aggregates one or more Go remote repositories. Each remote repository routes Go module requests through the Package Firewall. The virtual repository gives clients a single endpoint that forwards each request to the matching remote repository. You can use a single virtual repository to link all Go remote repositories. To create a Go remote repository: 1. [Log in to JFrog Artifactory](https://my.jfrog.com/login/). 2. Select **Administration** > **Repositories** from the left sidebar. 3. Click **Create a Repository** and select **Remote**. 4. Select **Go** as the package type. 5. Enter a **Repository Key**, for example `endor-firewall-go`. 6. Enter the repository URL: `https://factory.endorlabs.com/v1/namespaces//firewall/go/`. Replace `` with your Endor Labs namespace. 7. Enter the **User Name** and **Password** you saved when creating the API key. 8. Click **Create Remote Repository**. Create Go remote repository To create a virtual repository: 1. Select **Administration** > **Repositories** from the left sidebar. 2. Click **Create a Repository** and select **Virtual**. 3. Select **Go** as the package type. 4. Enter a **Repository Key**, for example `endor-firewall-go-virtual`. 5. Under **Repositories**, select the remote repositories you want to add and click **>**. 6. Click **Create Virtual Repository**. Create Go virtual repository Your Go remote and virtual repositories are now configured to route module requests through the Package Firewall. 1. [Log in to JFrog Artifactory](https://my.jfrog.com/login/). 2. Select **Administration** > **Repositories** from the left sidebar. 3. Click **Create a Repository** and select **Remote**. 4. Select **Maven** as the package type. 5. Enter a **Repository Key**, for example `endor-firewall-maven`. 6. Enter the repository URL: `https://factory.endorlabs.com/v1/namespaces//firewall/maven/`. Replace `` with your Endor Labs namespace. 7. Enter the **User Name** and **Password** you saved when creating the API key. 8. Disable **Offline** to allow Artifactory to fetch remote artifacts. 9. Select **Advanced** and enable **Store Artifacts Locally**. Optionally, enable **Priority Resolution** to prioritize this repository over other repositories. 10. Click **Create Remote Repository**. Configure Maven ### Local setup for developers Update your package manager to use Artifactory as its source, routing all installs through the Package Firewall instead of the public registry. Once you create the Artifactory remote: 1. Navigate to **Administration** > **Repositories**. 2. Click the vertical three dots next to the repository you configured and select **Set Me Up**. For Go, select the virtual repository you created. 3. Enter **Your JFrog account password** if prompted. 4. Click **Generate Token & Create Instructions**. 5. Follow the instructions to configure your local machine based on your package type. Edit `.npmrc` for npm, `pip.conf` for pip, or `settings.xml` for Maven. For Go modules, select **Resolve**, copy the URL it provides, and run the following command. Replace `` with the copied URL. Ensure to URL-encode any `@` in the username as `%40`. ```bash theme={null} go env -w GOPROXY= ``` Refer to [JFrog Artifactory documentation](https://docs.jfrog.com/artifactory/docs/use-artifactory-set-me-up-for-configuring-package-manager-clients) for more information. Local setup for developers 6. Run the following command to verify that your local client is pointing to the Artifactory repository. Ensure the output matches the Artifactory remote URL you configured, or the virtual repository URL for Go modules. * For npm packages, run `npm config get registry`. * For PyPI packages, run `pip3 config list | grep index-url`. * For Go modules, run `go env GOPROXY`. * For Maven packages, run `mvn dependency:resolve -s settings.xml`. ### Verify your setup To verify your setup, install a package that Endor Labs has classified as malware. The Package Firewall should block the installation and return an `HTTP 404`. The following are examples of packages classified as malware by Endor Labs. Run the following command to test the Package Firewall with npm. ```bash theme={null} npm install endor-firewall-test@1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `E404` error code and `404 Not Found` response confirm that the firewall blocked the package. ```bash theme={null} npm error code E404 npm error 404 Not Found - GET https://johndoe.jfrog.io/artifactory/api/npm/johndoe/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz npm error 404 npm error 404 The requested resource 'endor-firewall-test@https://johndoe.jfrog.io/artifactory/api/npm/johndoe/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz' could not be found or you do not have permission to access it. npm error 404 npm error 404 Note that you can also install from a npm error 404 tarball, folder, http url, or git url. ``` Run the following command to test the Package Firewall with pip. ```bash theme={null} pip install endor-firewall-test==1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `404` response confirms that the firewall blocked the package. ```bash theme={null} Defaulting to user installation because normal site-packages is not writeable Looking in indexes: https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/simple Collecting endor-firewall-test==1.0.0 ERROR: HTTP error 404 while getting https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/packages/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 (from https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/simple/endor-firewall-test/) (requires-python:>=3.7) ERROR: Could not install requirement endor-firewall-test==1.0.0 from https://johndoe.io/artifactory/api/pypi/johndoe/packages/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 because of HTTP error 404 Client Error: for url: https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/packages/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl for URL https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/packages/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 (from https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/simple/endor-firewall-test/) (requires-python:>=3.7) ``` Run the following command to test the Package Firewall with Go. ```bash theme={null} go install github.com/endorlabstest/endor-firewall-test@v1.0.0 ``` When the Package Firewall blocks the package, the output looks similar to the following. The `404` response confirms that the firewall blocked the package. ```bash theme={null} go get github.com/endorlabstest/endor-firewall-test@v1.0.0 go: github.com/endorlabstest/endor-firewall-test@v1.0.0: reading https://johndoe.com:xxxxx@johndoe.jfrog.io/artifactory/api/go/go-firewall-test-virtual/github.com/endorlabstest/endor-firewall-test/@v/v1.0.0.info: 404 ``` Add `io.github.endorlabs:endor-java-webapp-demo:4.1` as a dependency in your `pom.xml`, then run the following command to test the Package Firewall with Maven. ```bash theme={null} mvn dependency:resolve -s settings.xml ``` When the Package Firewall blocks the package, the output looks similar to the following. JFrog Artifactory does not serve the artifact, so resolution fails with a missing POM warning and a `Could not find artifact` error. ```bash theme={null} [INFO] Scanning for projects... [INFO] [INFO] -----------------------< com.example:my-app >------------------------ [INFO] Building my-app 1.0.0 [INFO] from pom.xml [INFO] --------------------------------[ jar ]--------------------------------- Downloading from endor-firewall: https://johndoe.jfrog.io/artifactory/endor-firewall-maven/io/github/endorlabs/endor-java-webapp-demo/4.1/endor-java-webapp-demo-4.1.pom [WARNING] The POM for io.github.endorlabs:endor-java-webapp-demo:jar:4.1 is missing, no dependency information available Downloading from endor-firewall: https://johndoe.jfrog.io/artifactory/endor-firewall-maven/io/github/endorlabs/endor-java-webapp-demo/4.1/endor-java-webapp-demo-4.1.jar [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE [INFO] ------------------------------------------------------------------------ [INFO] Total time: 4.000 s [INFO] Finished at: 2026-06-09T19:41:11+05:30 [INFO] ------------------------------------------------------------------------ [ERROR] Failed to execute goal on project my-app: Could not resolve dependencies for project com.example:my-app:jar:1.0.0 [ERROR] dependency: io.github.endorlabs:endor-java-webapp-demo:jar:4.1 (compile) [ERROR] Could not find artifact io.github.endorlabs:endor-java-webapp-demo:jar:4.1 in endor-firewall (https://johndoe.jfrog.io/artifactory/endor-firewall-maven) [ERROR] ``` After you confirm that the Package Firewall blocks malware, you can view the recorded events. See [View Package Firewall logs](/package-firewall/logs) to learn more. ## Troubleshooting and FAQ If Endor Labs flags a package as malware after Artifactory cached it, Artifactory continues to serve it until the cache expires. Use a short cache duration to reduce that window. * Verify that the Package Firewall URL in Artifactory is correct. * Ensure network connectivity from Artifactory to the Package Firewall. * Ensure the firewall rules allow outbound connections from Artifactory. * Verify the API key and secret are correct and that the key has the **Package Firewall User** role. * Ensure that the credentials are in the format Artifactory expects. * Check the Artifactory logs for authentication errors. * Verify that Artifactory has sufficient storage for the cache. * Set cache expiration to short durations so that more requests hit the Package Firewall. * Check the cache hit and miss rates. Clear the cache if you need to test with a fresh request. # View Package Firewall logs Source: https://docs.endorlabs.com/package-firewall/logs/index View, filter, and query the events the Package Firewall records for blocked and warned package installations. Package Firewall records the actions it takes on package installation requests, providing an audit trail for debugging and compliance. The logs include details such as the package name, version, event time, the reason the package was flagged, and the user who initiated the request. To view Package Firewall logs: 1. Select **Package Firewall** from the left sidebar. 2. Select an event to view the following details: * **Info**: Package name, package version, API key, remote address, user attribution, request type, request URL, action taken, the reason the event was flagged, and when the event occurred. User Attribution shows who made the request, as `@`. The MDM deployment scripts add this label to each machine's package manager credentials. See [User attribution](/package-firewall/mdm-deployment#user-attribution) to learn more. For malware events, you can also view the following details: * **Risk Details**: Explanation of why the package was flagged and remediation guidance. * **Metadata**: Ecosystem, package release date, advisory published date, CWE ID, and OSV ID when available. * **Malware Info**: Malware detection record in raw JSON format. For minimum package age events, you can also view the package age in hours. For restricted license events, you can also view the detected package license. For vulnerability events, you can also view the severity of the detected vulnerability. For curated events, you can also view the list of unsafe versions that were blocked, each labeled with its reason for blocking, either malware or minimum package age. See [Allow safe versions](/package-firewall/policy#allow-safe-versions) to learn more. Curated events ## Filter Package Firewall logs Use filters to narrow Package Firewall logs by ecosystem, action, rule reason, or time. 1. Select **Package Firewall** from the left sidebar. 2. Toggle the filter panel to show the filters. 3. Set any of the following filters to narrow the log list. * **Ecosystem** - Filter logs by their package ecosystem. * **Action**: Filter logs by the action taken on the package installation, either **Warning**, **Blocked**, or **Allowed safe versions**. * **Reason**: Filter logs by why the package was flagged, which can be **Malware detected**, **Minimum package age not met**, **Restricted license**, or **Curated**. * **All Time** - Filter logs by when the event was recorded. You can select **All Time**, **Last Day**, **Last Week**, **Last Month**, **Last 60 Days**, **Last 90 Days**, or a custom range. Curated events with the **Allowed safe versions** action are hidden by default. Select **Curated** in the **Reason** filter to view those logs. You can use the same filters to query logs through `endorctl`. See [Query Package Firewall logs using endorctl](#query-package-firewall-logs-using-endorctl). ## Query Package Firewall logs using endorctl The Package Firewall logs record every action the firewall takes on package installation requests. You can view them by querying the `endorctl` API. * To list all Package Firewall logs in your namespace, run the following command. Replace `` with your namespace. ```bash theme={null} endorctl api list -r PackageFirewallLog -n ``` * To list logs only for a specific ecosystem, add a filter. ```bash theme={null} endorctl api list -r PackageFirewallLog -n --filter 'spec.ecosystem==' ``` Replace: * `` with `ECOSYSTEM_NPM` for npm, `ECOSYSTEM_PYPI` for PyPI, `ECOSYSTEM_GO` for Go, and `ECOSYSTEM_MAVEN` for Maven. * `` with your namespace. * To list logs for a specific package in an ecosystem, use a filter with `spec.ecosystem`, `spec.package_name`, and `spec.package_version`. ```bash theme={null} endorctl api list -r PackageFirewallLog -n --filter 'spec.ecosystem== and spec.package_name=="" and spec.package_version==""' ``` Replace: * `` with your namespace. * `` with `ECOSYSTEM_NPM` for npm, `ECOSYSTEM_PYPI` for PyPI, `ECOSYSTEM_GO` for Go, and `ECOSYSTEM_MAVEN` for Maven. * `` with the package name you want to query. * `` with the package version you want to query. * To list logs attributed to a specific developer and machine, use a filter with `spec.user`. ```bash theme={null} endorctl api list -r PackageFirewallLog -n --filter 'spec.user==""' ``` Replace: * `` with your namespace. * `` with the attribution label you want to query, in the form `@`. * To count events for each attributed user, group logs by `spec.user`. Replace `` with your namespace. ```bash theme={null} endorctl api list -r PackageFirewallLog -n --group-aggregation-paths=spec.user ``` You can use a combination of filters to narrow your query. The API key created with `SYSTEM_ROLE_PACKAGE_FIREWALL` routes traffic through the Package Firewall. It does not grant access to the Package Firewall Log API. To query logs, create an API key with at least the **Read-only** role. For more information about roles and permissions, see [Authorization roles](/platform-administration/rbac/authorization-roles). # Deploy Package Firewall to developer machines with MDM Source: https://docs.endorlabs.com/package-firewall/mdm-deployment/index Generate self-contained scripts that configure developer machines to route package installations through Endor Labs Package Firewall, and push them with your MDM tool. Mobile device management (MDM) deployment lets an IT administrator configure many developer machines at once. You generate a self-contained script, push it through your MDM tool, and it configures each machine's package managers to route installations through Package Firewall. Developers do nothing, and existing package-manager configuration is preserved. The scripts cover the following ecosystems. They are idempotent, so they are safe to re-run on every MDM check-in, and they have no runtime dependencies beyond the shell. The scripts are available in the [Endor Labs MDM scripts repository](https://github.com/endorlabs/mdm-scripts) under the [`package-firewall/` directory](https://github.com/endorlabs/mdm-scripts/tree/main/package-firewall). ## Before you begin Create an API key dedicated to the Package Firewall so that can authenticate to it. You can create it through one of the following methods: * Using the Endor Labs user interface, with the **Package Firewall User** role. See [API keys](/platform-administration/api-keys#create-an-api-key-through-the-endor-labs-user-interface) to learn more. * Using endorctl, with the `SYSTEM_ROLE_PACKAGE_FIREWALL` role. Make sure to [install and configure endorctl](/developers-api/cli/install-and-configure) before you create the key. To create the key using endorctl, run the following command and replace: * `` with your namespace. * `` with the name of the API key for the Package Firewall use case. * `` with the API key expiration in ISO 8601 UTC format, for example `2026-12-31T23:59:59Z`. ```bash theme={null} export NAMESPACE="" export KEY_NAME="" endorctl api create -r APIKey -n "$NAMESPACE" --data '{ "meta": { "name": "'"$KEY_NAME"'" }, "spec": { "permissions": { "roles": ["SYSTEM_ROLE_PACKAGE_FIREWALL"] }, "expiration_time": "" }, "propagate": true }' ``` ## Generate the MDM scripts Clone the generator repository and run it with your namespace and Package Firewall credentials. Select your platform for the matching commands. You can also generate the scripts in the browser using the [MDM script generator](#generate-your-mdm-script-in-the-browser). The generator fetches the real source files from the Endor Labs MDM scripts repository ([https://github.com/endorlabs/mdm-scripts](https://github.com/endorlabs/mdm-scripts)). The GitHub repository is the authoritative source for the scripts. 1. **Clone the generator repository**: Clone the repository and change into the bash generator directory. ```bash theme={null} git clone https://github.com/endorlabs/mdm-scripts cd mdm-scripts/package-firewall/bash ``` 2. **Generate the scripts**: Pass your credentials as environment variables. This keeps them out of your shell history. ```bash theme={null} ENDOR_NAMESPACE= \ ENDOR_API_KEY_ID= \ ENDOR_API_SECRET= \ ./generate.sh ``` Alternatively, store the variables in a `.env` file, add `.env` to `.gitignore`, and source it. ```bash theme={null} set -a; source .env; set +a ./generate.sh ``` The generator writes `endor-js.sh`, `endor-python.sh`,`endor-go.sh`, `endor-maven.sh`, `endor-all.sh`, and `endor-remove.sh` to `out//`. Re-running `generate.sh` overwrites the same directory. 1. **Clone the generator repository**: Clone the repository and change into the PowerShell generator directory. ```powershell theme={null} git clone https://github.com/endorlabs/mdm-scripts cd mdm-scripts/package-firewall/powershell ``` 2. **Generate the scripts**: Set your credentials as environment variables, then run the generator. ```powershell theme={null} $env:ENDOR_NAMESPACE = '' $env:ENDOR_API_KEY_ID = '' $env:ENDOR_API_SECRET = '' ./generate.ps1 ``` The generator writes `endor-js.ps1`, `endor-python.ps1`, `endor-go.ps1`, `endor-maven.ps1`, `endor-all.ps1`, and `endor-remove.ps1` to `out//`. Re-running `generate.ps1` overwrites the same directory. The generated scripts contain your API key and secret in plain text, because the scripts need them to write credentials on each device. Treat the scripts, and the MDM policy that holds them, as secrets. Restrict access to the policy, add the `out/` directory to `.gitignore`, and rotate your API key if a script is exposed. ## Upload the scripts to your MDM tool Each generated script is self-contained with no runtime dependencies, so you upload it directly to your MDM tool. On macOS and Linux the scripts use the `.sh` extension; on Windows they use `.ps1`. Run the scripts as `root`. The script detects the logged-in console user and writes configuration files to the correct home directory. 1. **Add the script**: Go to **Library** > **Custom Scripts** > **Add Script**. 2. **Provide the script**: Paste the script content or upload the file. 3. **Set the run context**: Set **Run as** to **Root**. 4. **Set the frequency**: Set **Execution Frequency** to **Run once per device**, or to every check-in for ongoing enforcement. 5. **Assign the script**: Assign the script to the relevant device blueprint. 1. **Add the script**: Go to **Settings** > **Scripts** > **New** and paste the script content. 2. **Create a policy**: Go to **Policies** > **New Policy** > **Scripts** and add your script. 3. **Set the frequency**: Set the **Execution Frequency** as appropriate. 4. **Scope the policy**: Scope the policy to the target devices. Upload the script file and run it as **root**. The script detects the logged-in console user and writes configuration files to the correct home directory. Run the scripts as **SYSTEM**. The script detects the logged-in console user through `explorer.exe` and writes configuration files to the correct user profile. 1. **Add the script**: Go to **Devices** > **Scripts and remediations** > **Platform scripts** > **Add**. 2. **Upload the file**: Upload the `.ps1` file. 3. **Set the run context**: Set **Run this script using the logged on credentials** to **No**, so the script runs as SYSTEM. 4. **Set the signature check**: Set **Enforce script signature check** to **No**. 5. **Set the PowerShell architecture**: Set **Run script in 64-bit PowerShell** to **Yes**. 6. **Assign the script**: Assign the script to the target device group. Intune bypasses the execution policy for managed scripts, so you do not need to change the device policy. Upload the script file and run it as **SYSTEM**. The script detects the logged-in console user through `explorer.exe` and writes configuration files to the correct user profile. ## How credentials are stored The scripts write your credentials to a single source on each device and reference them from the package-manager configuration files. The storage mechanism depends on your platform. The scripts write all credentials to `~/.config/endor/env.sh` and set the file permissions to `600`. ```bash theme={null} export ENDOR_API_KEY_ID="..." export ENDOR_API_SECRET="..." export ENDOR_ATTR_USER="..." # attributed Basic-auth username, see User attribution export ENDOR_AUTH_B64="..." # base64(attributed-user:secret) for npm, pnpm, yarn, and bun export ENDOR_API_SECRET_B64="..." export ENDOR_NPM_REGISTRY_URL="..." # for npm and yarn 2+ export POETRY_HTTP_BASIC_ENDOR_FIREWALL_USERNAME="..." # attributed user export POETRY_HTTP_BASIC_ENDOR_FIREWALL_PASSWORD="..." ``` Each shell profile (`.zshrc`, `.bash_profile`, and `.bashrc`) gets a one-line block that sources this file. The configuration files reference these variables instead of embedding credentials, except `pip.conf`, `uv.toml`, and the go env file, which cannot expand variables and get a literal index URL baked in at install time. To rotate credentials, redeploy the MDM script to update `env.sh` on the target machines. No configuration file changes are needed. The scripts write persistent user-level environment variables to the `HKCU:\Environment` registry key. ```text theme={null} ENDOR_API_KEY_ID = ENDOR_API_SECRET = ENDOR_ATTR_USER = ENDOR_AUTH_B64 = ENDOR_API_SECRET_B64 = ENDOR_NPM_REGISTRY_URL = https://factory.endorlabs.com/v1/namespaces//firewall/npm/ POETRY_HTTP_BASIC_ENDOR_FIREWALL_USERNAME = POETRY_HTTP_BASIC_ENDOR_FIREWALL_PASSWORD = ``` Every process the user starts inherits `HKCU:\Environment` variables, including Makefiles, git hooks, IDE terminals, and scheduled tasks. No shell profile sourcing is required. `pip.ini`, `uv.toml`, and the go env file cannot expand environment variables, so they get a literal index URL baked in at install time instead. To rotate credentials, redeploy the MDM script. It updates `HKCU:\Environment`, plus `pip.ini`, `uv.toml`, and the go env file, which hold literal credentials, in place. ## User attribution The generated scripts label each machine's Package Firewall traffic with the developer who owns it. The activity in the firewall logs is attributed to a person and machine rather than to a shared API key. At install time the script builds a `@` label from the logged-in console user and the machine name. Then it encodes the label into the Basic-auth username it writes for every package manager (npm, pnpm, yarn, bun, pip, uv, Go, and Maven). This username is stored as `ENDOR_ATTR_USER` in the credential store, which is `env.sh` on macOS and Linux and `HKCU:\Environment` on Windows. The firewall decodes the label, authenticates the request with your API key, and records the label as the user on the request. Attribution is informational. Access is still controlled by the API key ID and secret you generate. The label does not grant or restrict any permission, and rotating the key does not change how attribution works. You can view the attributed user on each event in the Package Firewall logs and query the logs by attributed user. See [View Package Firewall logs](/package-firewall/logs) to learn more. ## What the scripts do Each install script writes the credential store and an Endor-managed block to the package-manager configuration files. The file locations depend on your platform. The `endor-js.sh` script writes `~/.config/endor/env.sh` and an Endor-managed block to the following files. The `endor-go.sh` script writes `~/.config/endor/env.sh` and an Endor-managed block to the following file. The `endor-python.sh` script writes `~/.config/endor/env.sh` and an Endor-managed block to the following files. The `endor-maven.sh` script writes `~/.config/endor/env.sh` and an Endor-managed block to the following file. The `endor-js.ps1` script writes the registry environment variables and an Endor-managed block to the following files. The `endor-go.ps1` script writes the registry environment variables and an Endor-managed block to the following file. The `endor-python.ps1` script writes the registry environment variables and an Endor-managed block to the following files. The `endor-maven.ps1` script writes the registry environment variables and an Endor-managed block to the following file. ### How each package manager is configured The scripts apply a few package-manager-specific behaviors that are the same on every platform. * JavaScript: The scripts write `_auth` (base64) instead of `_authToken`, which bun requires. Yarn classic reads authentication from `.npmrc`, so the `.npmrc` write covers it. The scripts do not write the project-level `bunfig.toml`. * Go: The scripts resolve the go env file path with `go env GOENV`, then write `GOPROXY` to it. If `go` is not installed, they fall back to the OS default path (`~/Library/Application Support/go/env` on macOS, `~/.config/go/env` on Linux, or `%APPDATA%\go\env` on Windows). Credentials are literal because go env files cannot expand environment variables. The `GOPROXY` value ends in `,direct`, so Go downloads a module directly from its source when the firewall does not serve it. The go env file applies to every `go` command regardless of shell, and it has lower precedence than the `GOPROXY` process variable, so project-level overrides still work. * Python (pip): The scripts write the pip settings in a `[global]` section. If the file already has a `[global]` section, they merge the Endor keys into it, because pip rejects duplicate `[global]` sections. Any conflicting keys, such as an existing `index-url`, are disabled with an `#endor-bak#` prefix and restored when the remove script runs. Credentials are literal because pip cannot expand environment variables. * Python (uv): uv ignores `pip.conf`, so the scripts write the user-level `uv.toml` with the firewall index URL. The URL is baked in literally because uv cannot expand environment variables in its config, so it carries the attributed username. * Maven: The scripts write a user-level `settings.xml` (`~/.m2/settings.xml`, or `%USERPROFILE%\.m2\settings.xml` on Windows) with a `` of `*` that points at the firewall, plus a matching ``. Credentials are not baked into the file. The `` references `${env.ENDOR_ATTR_USER}` and `${env.ENDOR_API_SECRET}`, which Maven resolves at runtime from the environment variables the credential store already sets. Gradle uses this too when it reads `~/.m2/settings.xml`. * Python (Poetry): Poetry reads credentials from the `POETRY_HTTP_BASIC_ENDOR_FIREWALL_*` environment variables, so no separate write step is needed. Add the source to your `pyproject.toml`: Poetry reads the registry URL from `pyproject.toml` and the credentials from environment variables. Add the Package Firewall as a source in each project. The source includes the URL only, never the credentials. ```toml theme={null} [[tool.poetry.source]] name = "endor-firewall" url = "https://factory.endorlabs.com/v1/namespaces//firewall/pypi/simple/" priority = "primary" ``` ## Preserve existing configuration The scripts use a sentinel block pattern. Each script writes only a clearly delimited section to a configuration file and leaves everything else untouched, so existing settings survive every deployment. The following example shows an `.npmrc` file that already contains administrator settings. The script adds only the Endor-managed block between the `BEGIN` and `END` markers. ```ini theme={null} # Existing configuration — never touched legacy-peer-deps=true # ===== BEGIN ENDOR PACKAGE FIREWALL (managed — do not edit) ===== registry=https://factory.endorlabs.com/v1/namespaces//firewall/npm/ always-auth=true //factory.endorlabs.com/v1/namespaces//firewall/npm/:_auth=${ENDOR_AUTH_B64} # ===== END ENDOR PACKAGE FIREWALL ===== ``` The following table describes how the scripts handle each configuration scenario. ## Remove the configuration To offboard a machine, deploy the remove script. It strips the Endor block from every managed file and removes the credentials the install scripts added. Deploy `endor-remove.sh`. It removes the Endor block from each configuration file and removes the credentials from `~/.config/endor/env.sh`. Deploy `endor-remove.ps1`. It removes the Endor block from each configuration file, deletes the `ENDOR_*` and `POETRY_HTTP_BASIC_ENDOR_FIREWALL_*` values from `HKCU:\Environment`, and deletes configuration files that are empty after block removal. Preview the changes with `-DryRun` before you apply them. ```powershell theme={null} .\endor-remove.ps1 -DryRun .\endor-remove.ps1 ``` ## Security notes The scripts store credentials on each device. Review the following before you deploy. ## Generate your MDM script in the browser Select your platform, ecosystem, and MDM tool, then enter your namespace and API key. The script is generated entirely in your browser: your credentials are never sent to Endor Labs or GitHub, only baked into the script you download. The generated script contains your API key and secret in plain text, because they are needed to write credentials on each device. Treat the script, and the MDM policy that holds it, as secrets. Restrict who can view the policy, add generated scripts to `.gitignore`, and rotate your API key if a script is exposed. # Package Firewall policy Source: https://docs.endorlabs.com/package-firewall/policy/index Configure how Package Firewall responds to flagged packages, including block, warn, and allow safe versions actions, exceptions, vulnerabilities, restricted licenses, and minimum package age. Package Firewall proxies package installations between your private registry and the public package indexes, evaluating each request in real time before download. Use a policy to control which installations are blocked or allowed. For packages that fail the policy, you can block the download, allow it and record a warning, or remove only the unsafe versions so a safe version installs instead. Configure the Package Firewall policy to block a package installation, allow it and record a warning, or allow only the safe versions of a package. * **Block**: Prevents the package installation and returns an error. Select this action when you want to ensure the package never reaches your environment. * **Warn**: Allows the package installation and logs it as a warning event. Select this action when you want visibility without risking build interruptions. * **Allow safe versions only (curate)**: Removes the unsafe versions from the list of versions available to the package manager, so it resolves and installs a safe version instead of failing. Developers get a working version without seeing a block. This action is available for the malware and minimum package age conditions. See [Allow safe versions](#allow-safe-versions) to learn more. Package Firewall enforces these actions based on the conditions you configure in the policy. * **Exceptions**: Specify packages to exclude from enforcement. When a package matches an exception, Package Firewall skips all checks and allows the installation. Exceptions override other conditions such as restricted licenses and minimum package age, making them useful for approved packages that must remain available for critical builds and package installation workflows. You can define exceptions for a single version, multiple versions, or a version range. For version ranges, the lower bound is inclusive and the upper bound is exclusive. If you do not configure version limits, the exception applies to every version of that package for the selected ecosystem. Exceptions apply only to the packages explicitly listed and do not cover transitive dependencies. If a transitive dependency is flagged, it is blocked even if the parent package has an exception. Add that package as a separate exception to allow its installation. * **Vulnerabilities**: Set a CVSS severity threshold. Endor Labs uses CVSS 3.x by default and evaluates vulnerability severity using that version. You can change the CVSS version for your namespace in [System Settings](/platform-administration/configure-system-settings/#configure-cvss-score-version). If a package has a known vulnerability at or above this threshold, the configured policy action is applied. * **Restricted licenses**: You can define a list of SPDX licenses that your organization considers restricted. If a package version matches one of these licenses, Endor Labs applies the configured policy action, helping enforce legal and open-source compliance at install time. * **Minimum package age**: Set a minimum number of hours that must pass after a version is published before it is considered safe. If a version is newer than this threshold, Endor Labs applies the configured policy action, mitigating risk from newly released packages. Endor Labs records every package installation request together with the action taken. See [View Package Firewall logs](/package-firewall/logs) to learn more. **License requirement** Ensure that you have the **Package Firewall** license to configure the policy. See [Licenses](/introduction/licenses) for more information. ### Allow safe versions When you set the malware or minimum package age action to **Allow safe versions only (curate)**, Package Firewall filters the versions it returns so the package manager can resolve from only safe versions. If no safe version is available, Package Firewall blocks the request. 1. When the package manager requests a list of available versions, Package Firewall removes any versions flagged as malware or younger than the minimum package age, then returns only the remaining safe versions. 2. The package manager resolves the most compatible version from the safe list and requests it. 3. Package Firewall evaluates the selected version against any configured restricted license and vulnerability conditions. If the version matches one of those conditions, Package Firewall warns or blocks the installation according to the configured action. The Package Firewall log records this event with the action **Allowed safe versions** and the reason **Curated**. This action applies only to the malware and minimum package age conditions. It does not apply to restricted license or vulnerability conditions, which Package Firewall always evaluates after the package manager selects a version. This action is available for the npm and PyPI ecosystems. Package Firewall can filter the version list only when the package manager requests a list of available versions rather than an exact version. The Package Firewall blocks the request and logs the event with the action **Blocked** and the reason **Curated**, when either of the following conditions are met: * The installation requests an exact version, and that version is unsafe. * All available versions are unsafe and Package Firewall has no safe version to return. ## Configure the policy You can configure the Package Firewall policy to block or warn installations based on malware detection, exceptions, vulnerabilities, restricted licenses, and minimum package age conditions. The Package Firewall evaluates each package against the policy in the following order: **Exceptions → Malware → Vulnerability → Restricted License → Minimum Package Age**. If a package is listed as an exception, all checks are skipped. If a check matches and the action is **Warn**, the event is logged and the evaluation continues. If the action is **Block**, the installation is blocked and all checks are skipped. When the malware or minimum package age action is set to allow safe versions only, Package Firewall filters the version list instead of blocking the request. See [Allow safe versions](#allow-safe-versions) to learn more. You can also set up notifications to receive Slack messages when the firewall blocks or warns on a package installation. See [notifications](#set-up-notifications) to learn more. Before configuring the policy, set up a Package Firewall integration in your namespace. See [Package Firewall](/package-firewall/) for setup instructions. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Package Firewall Policies**. ### Configure malware detection Set the action the Package Firewall takes when it detects malware in a package. 1. Select **Malware**. 2. Choose **Block**, **Warn**, or **Allow safe versions only (curate)** if the package is flagged as malicious. 3. Click **Save**. ### Set a minimum package age Block or warn package installations when a version was published more recently than a threshold you define. 1. Select **Minimum Package Age**. 2. Enter the number of hours that must pass after a version is published before it can be installed in **Minimum package age in hours**. 3. Choose **Block**, **Warn**, or **Allow safe versions only (curate)** if the condition is met. 4. Click **Save**. ### Restrict licenses Define the SPDX licenses your organization considers restricted and how the Package Firewall responds when a restricted license is detected. Restricted license enforcement does not apply to the Go ecosystem. 1. Select **Restricted License**. 2. Click **Add Licenses**. 3. Search for and select the licenses you want to restrict. You can search by the SPDX name or identifier of the license. 4. If you don't find the licenses you are looking for, enter a comma separated list of licenses in **Add custom licenses**. 5. Click **Add & select**. 6. Click **Save**. 7. Choose to **Block** or **Warn** if the condition is met. 8. Click **Save**. Restricted licenses ### Set a vulnerability threshold Block or warn package installations that have vulnerabilities at or above a CVSS severity threshold. 1. Select **Vulnerability**. 2. Choose **High** or **High & Critical** in **Select CVSS severity**. Choose **Do nothing** to skip the vulnerability check. 3. Choose to **Block** or **Warn** if the condition is met. 4. Click **Save**. ### Add exceptions Add packages that bypass the Package Firewall entirely, skipping all malware, license, vulnerability, and minimum-age checks for those installations. 1. Select **Exceptions**. 2. Click **Add package exceptions**. 3. Choose the **Ecosystem**. 4. Enter the **Package name**. 5. Optionally, turn on **Specify versions** and apply the exception to specific versions. If you leave this off, all versions of the package bypass the Package Firewall. * To exclude a specific version, choose **Exact version** and enter the version to exclude. * To exclude a range of package versions, choose **Version range** and enter the lower and upper bounds. The lower bound is inclusive, and the upper bound is exclusive. For example, a range of `1.1.3` to `3.0.0` matches version `1.1.3`, but not `3.0.0`. Click **+** to add a row for each additional version or range you want to exclude for that package. Add exceptions 6. Click **Save**. 7. Optionally, click **Add more** to add exceptions for other packages. To update an exception: 1. Click the vertical three dots and select **Edit**. You can update the package manager, package name, and versions. 2. Click **Save**. To delete an exception, click the vertical three dots and select **Delete**. ### Set up notifications Configure Package Firewall notifications to send a Slack message when the firewall blocks or warns on a package installation. Each notification covers the conditions you choose, such as malware, minimum package age, restricted licenses, or vulnerabilities. You can configure multiple notifications for different conditions. A notification is sent only when an event matches both a selected reason and a selected action. The reason must already be configured to block or warn in your policy for it to generate a notification. Ensure that you have at least one Slack notification target before you create a notification. Only Slack targets are supported. See [Slack integration](/integrations/slack) to set one up. 1. Select **Notifications**. 2. Click **Add notification**. 3. Enter a **Name** for the notification. 4. Select one or more reasons: **Malware**, **Minimum Package Age**, **Restricted License**, or **Vulnerability**. 5. Select one or more actions: **Block** or **Warn**. 6. Search for and select the Slack targets that receive the notifications. 7. Click **Save**. Notifications To edit a notification: 1. Click the vertical three dots and select **Edit**. You can update the notification name, reasons, actions, and Slack targets. 2. Click **Save**. To delete a notification, click the vertical three dots and select **Delete**. # Package Firewall troubleshooting and FAQ Source: https://docs.endorlabs.com/package-firewall/troubleshooting/index Answers to common questions about how the Package Firewall handles malware, transitive dependencies, performance, and version ranges. No. The Package Firewall blocks only the specific package versions that Endor Labs flags as malware in the malware database. The Package Firewall checks each package individually when the client requests it during installation. If any dependency, direct or transitive, contains malware, the firewall blocks that specific package installation and stops the overall installation process. No. The impact on installation time is minimal. The package manager resolves version ranges as usual. The Package Firewall checks the resolved version when the client requests it for download. If Endor Labs flags that version as malware, the firewall blocks the installation. # Manage API keys Source: https://docs.endorlabs.com/platform-administration/api-keys/index Manage your Endor Labs API keys for automation. Use API keys to engage with Endor Labs services programmatically and enable any automation or integration with other systems in your environment. You can manage API keys with endorctl or from the Endor Labs user interface. API keys are region-bound. If you're using a EU tenant, create your API keys from within your EU tenant at `https://app.eu.endorlabs.com`. Instead of using API keys, you can use keyless authentication to authenticate with Endor Labs services. See [Keyless authentication](/setup-deployment/ci-cd/keyless-authentication) for more information. Using keyless authentication eliminates the need to manage API keys and reduces the risk of API key compromise. See [API key management best practices](/best-practices/manage-api-keys) for more information on how to manage API keys. ## Create an API key Create an API key to access Endor Labs services programmatically. You can create an API key either from the user interface or using the Endor Labs API. You can create API keys with an expiry of up to one year from the user interface. Use the API to create keys with longer expiry. ### Create an API key through the Endor Labs user interface 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **API Keys**. 3. Click **Generate API Key**. 4. Enter a name to identify the API key. 5. Select the [roles](/platform-administration/rbac/authorization-roles) to apply to the API Key. You can choose from the following options: * Admin * Read-only * Code Scanner * Policy Editor * On-Prem Scheduler * Package Firewall User * AI Audit User 6. Select the expiry of the API key. You can set the value as 30, 60, 90 days, or one year. 7. When you create an API key, it applies to the current namespace and all its child namespaces. To prevent the policy from being applied to any child namespace, click **Advanced** and deselect **Propagate this policy to all child namespaces**. Using these credentials, you can configure Endor Labs scans in your CI/CD pipeline. Each session initiated by the API key is valid up to four hours. See [scanning with endorctl](/scan/sca) for details. ### Create an API key through Endor Labs API Run the following command to generate and API with the [create API Key endpoint](/api-reference/apikeyservice/createapikey). ```shell theme={null} endorctl api create -r APIKey --data '{ "meta": { "name": "API Key name", "description": "API key description" }, "spec": { "permissions": { "roles": ["SYSTEM_ROLE_ADMIN"] }, "expiration_time": "2025-05-01T00:00:00Z" } } ``` You can use the following values in `spec.permissions.roles`: * `SYSTEM_ROLE_ADMIN` * `SYSTEM_ROLE_READ_ONLY` * `SYSTEM_ROLE_POLICY_EDITOR` * `SYSTEM_ROLE_CODE_SCANNER` * `SYSTEM_ROLE_PACKAGE_FIREWALL` * `SYSTEM_ROLE_AI_AUDIT` Use `SYSTEM_ROLE_AI_AUDIT` for API keys that ship with [Coding Agent Governance](/agent-governance/prerequisites) hooks on developer machines. See [authorization roles](/platform-administration/rbac/authorization-roles) for more information. You can provide a specific value for the expiration date of the token. You can also set an expiry of over one year if required. You cannot edit the expiry after you create the API key. If you want to change the expiry, create a new API key with the required expiry date. For example, you want to create an API key for a CI/CD pipeline that expires on March 31st 2026. Run the following command to create an API key with `SYSTEM_ROLE_CODE_SCANNER` role so that you can use it for endorctl access from a CI/CD pipeline. ```shell theme={null} endorctl api create -r APIKey --data '{ "meta": { "name": "CI/CD Access API key", "description": "API key for use within the CI/CD pipeline" }, "spec": { "permissions": { "roles": ["SYSTEM_ROLE_CODE_SCANNER"] }, "expiration_time": "2026-03-31T00:00:00Z" } }' ``` ```shell expandable theme={null} { "meta": { "create_time": "2025-03-11T16:29:06.127975636Z", "created_by": "xxxxxx@endor.ai@google@api-key", "description": "API key for use within the CI/CD pipeline", "kind": "APIKey", "name": "CI/CD Access API key", "update_time": "2025-03-11T16:29:06.127975636Z", "updated_by": "xxxxxx@endor.ai@google@api-key", "version": "v1" }, "spec": { "expiration_time": "2026-03-31T00:00:00Z", "issuing_user": { "meta": { "name": "xxxxxx@endor.ai@google@api-key" }, "spec": { "email": "", "first_name": "", "last_login_time": "2025-03-11T16:29:06.114662511Z", "last_name": "", "user_name": "" } }, "key": "endr+foo", "permissions": { "roles": [ "SYSTEM_ROLE_CODE_SCANNER" ] }, "secret": "endr+bar" }, "tenant_meta": { "namespace": "demo" }, "uuid": "67dx6x6x6f69xxx777a41cda" } ``` ## Delete an API Key Delete the API keys that are expired or no longer in use. You can delete API keys using the Endor Labs user interface or using the Endor Labs API. ### Delete an API key through the Endor Labs user interface 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **API Keys**. 3. Find the API key that you want to delete and click **Delete**. ### Delete an API key through Endor Labs API Run the following command to delete an API key with the [delete API Key endpoint](/api-reference/apikeyservice/deleteapikey). ```shell theme={null} endorctl api delete -r=APIKey --name= ``` The command fails if there are multiple API keys with the same name. You can use the UUID to delete a specific API key. ```shell theme={null} endorctl api delete -r=APIKey --uuid= ``` # Configure system settings Source: https://docs.endorlabs.com/platform-administration/configure-system-settings/index Configure Endor Labs application system settings to define the application behavior. Administrators can configure the following settings to customize certain interactions with Endor Labs. These interactions include: * [Configure CVSS score version](#configure-cvss-score-version) * [Configure data privacy settings](#configure-data-privacy-settings) * [Configure developer workflow settings](#configure-developer-workflow-settings) * [Allow ignore files to dismiss findings](#allow-ignore-files-to-dismiss-findings) * [Configure Endor Patches settings](#configure-endor-patches-settings) * [Configure policy settings](#configure-policy-settings) * [Configure SBOM settings](#configure-sbom-settings) * [Configure urgent notification settings](#configure-urgent-notification-settings) ## Configure CVSS score version Endor Labs supports choosing between CVSS v4 and v3 scoring from vulnerability providers so that organizations can standardize their security assessments. When CVSS v4 is enabled, vulnerability severities are determined using CVSS v4.x scores. Integrations with Vanta only support CVSS v3. If you are exporting vulnerability details to Vanta, only CVSS v3 data is included. Endor Labs uses CVSS 3.x to report vulnerabilities by default. To enable CVSS 4.x scoring: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **SYSTEM SETTINGS** > **CVSS Version**. 3. Choose **CVSS 4.x**. 4. Click **Save CVSS Version Settings**. CVSS settings ## Configure data privacy settings Use data privacy settings to manage how your scan logs are handled to improve monitoring and visibility. To configure data privacy settings: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **SYSTEM SETTINGS** > **Data Privacy**. 3. Select **Remote Logging** to send scan logs to a centralized logging system for improved monitoring and debugging. 4. Select **Code Snippet Storage** to store and display code snippets that triggered SAST findings. 5. Select **Code Segment Embeddings and LLM Processing** to use embeddings and LLM processing to improve C/C++ and AI model detection accuracy. 6. Click **Save Data Privacy Settings** to save your changes. Data Privacy ## Configure developer workflow settings Use developer workflow settings to control whether scans use ignore files in your repositories and to specify which paths are treated as ignore files. ### Allow ignore files to dismiss findings Use ignore files to codify approved exceptions so that known, accepted vulnerabilities and other findings are ignored before they surface in the scan results. This lets teams manage exceptions as code, enabling developers and AppSec teams to review, track and version-control ignore decisions alongside the application, avoid noisy or redundant results, and prevent downstream automations, such as alerts, tickets, and PR checks, from firing on issues that have already been explicitly accepted as risk. Ignore files must follow the supported yaml format where each entry specifies finding details and metadata such as expiration date and reason. For vulnerability findings only, the file may instead be a raw list of vulnerability IDs. Use the [endorctl ignore](/developers-api/cli/commands/ignore) command to generate and format the yaml ignore file, and the [endorctl validate ignore](/developers-api/cli/commands/validate/ignore) command to validate the file after updates or branch merges. To enable ignore file support: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **SYSTEM SETTINGS** > **Developer Workflows**. 3. Select **Allow ignore files to dismiss findings** to enable the feature. 4. Optionally, under **Ignore file paths**, customize the list of supported ignore file paths. By default, `.endorignore.yaml` is supported. You can add more file paths, for example, `.endorignore.yaml`, `custom-ignore.yaml`, `src/java/endorignore.yaml`, to allow scans to recognize multiple ignore files in a repository. If you specify a list of custom file paths that does not include `.endorignore.yaml` then the default file will no longer be processed by the scan. The configured file paths apply to all projects in the tenant. 5. Click **Save Workflows Settings**. Developer workflow settings **Recommendation** Set up CODEOWNERS for all supported ignore files, for all projects, so that ignore entries require approval before they can be merged. ## Configure Endor Patches settings Use Endor Patches settings to activate auto patching for all your projects in your tenant with the supported ecosystems. To configure Endor Patches settings: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **SYSTEM SETTINGS** > **Endor Patches**. 3. Select **Auto Patch Vulnerable Dependencies** to apply vulnerability fixes to your applications without changing your code 4. Click **Save Patch Settings**. Changes to auto patching settings may take up to ten minutes to take effect. Endor Patches ## Configure policy settings Endor Labs comes with multiple out-of-the-box policies that help you ensure the security posture of your code repositories, detect secret leaks, discern license risks, and make your code compliant with the CIS benchmark. Endor Labs regularly updates its existing policies and also includes new policies. Configure policy settings to ensure that you benefit from these regular updates. To configure policy settings: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **SYSTEM SETTINGS** > **Policies & Rules**. 3. Select **Enable Policies for New Features** to ensure that new policies released by Endor Labs are automatically enabled for your projects. This ensures that the policies are automatically applied and you can view the generated findings. 4. Select **Upgrade Policies to Latest Version** to ensure that any updates released by Endor Labs to the existing policies are automatically applied for your projects. 5. Click **Save Policy Settings**. policy settings ## Configure SBOM settings You can configure organizational settings that will be included in every one of your organization's SBOMs. These settings allow you to meet NTIA requirements for minimum SBOM data fields which require supplier contact information for your organization. To define your organization's SBOM settings: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **SYSTEM SETTINGS** > **SBOM**. 3. Enter the following organizational SBOM settings as appropriate for your organization under **SBOM Settings**. * **Organizational Name** - The organization that supplied the library or application that the SBOM describes. * **Contact Name** - A contact at the organization for SBOM related inquiries. * **Contact Email Address** - The organizational contact's email address. * **Supplier URL** - The website URL of the organization supplying the SBOM. 4. Click **Save SBOM Settings**. SBOM settings ## Configure urgent notification settings Beta Urgent notifications deliver real-time alerts about newly discovered malware that could impact your projects. These alerts are sent independently of your notification policy settings, enabling your security teams to take immediate action without waiting for the next scan cycle. To configure urgent notification settings: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **SYSTEM SETTINGS** > **Urgent Notifications**. 3. Select **Enable urgent notification** to turn on alerts for malicious packages. 4. Select the **Setup Threshold** to define which affected package versions trigger notifications. * **Notify when definitely affected**: Receive notifications when a malicious package version exactly matches a dependency version used in your projects. * **Notify when potentially affected**: Receive notifications when a malicious package is detected among your dependencies, even if the versions differ. 5. Enter email addresses to receive these notifications in your inbox. 6. Optionally, enter a Slack webhook URL to receive them in Slack. See [Create incoming webhooks in Slack](/integrations/slack#create-incoming-webhooks-in-slack) to create one. 7. Click **Save Urgent Notifications Settings**. Urgent notifications # Platform Administration Source: https://docs.endorlabs.com/platform-administration/index Configure and manage important settings of the Endor Labs platform. Learn about the administrative features to configure and manage important settings of the Endor Labs platform, such as scan profiles, policies, access control, and more. View license details and usage over time. Manage user and machine access, authentication providers, authorization policies, and invitations. Organize projects into logical partitions and define hierarchy for teams and business units. Create and manage finding, action, exception, and remediation policies. Configure scan profiles and build tools to customize how projects are scanned. Manage API keys for automation and integrations. Configure data privacy, patches, policy, notifications, and SBOM settings. Configure proxy settings for machines with proxy-only internet access. # License Source: https://docs.endorlabs.com/platform-administration/license/index View your license details and license consumption across your organization. Endor Labs licenses are sold in seats and billed annually, with each seat occupied by one contributing developer. Your license defines your available features and seat entitlement. See [Endor Labs licenses](/introduction/licenses) for the full licensing model, SKUs, and per-seat entitlements. You can view your product bundle, current plan, expiration date, enabled features, scan credits, and license consumption to monitor usage throughout your contract term and plan for renewals. Only users with the **Admin** role in the root namespace can view license details. See [Authorization roles](/platform-administration/rbac/authorization-roles) to learn about roles. To view license details: 1. Select **Settings** from the user menu. 2. Select **License**. 3. Select **License Info** from the left sidebar. License information ## Contributing developers License consumption is measured in contributing developers. A contributing developer is any developer who has committed code to a scanned branch in the past 90 days. Each developer is counted once across all namespaces in your tenant, deduplicated by commit email and source code management (SCM) identity. The license consumption count is the total number of unique contributing developers at a point in time. Commits made to pull request branches are not counted. Click **Download CSV** to download the list of contributing developer email addresses, SCM IDs, host URLs, and verification status as a CSV file. The verification status column shows **Yes** for verified contributors and **No** for unverified ones. Contributing developers Each contributing developer is classified as verified or unverified, which determines how accurately they are counted toward your license consumption. * **Verified**: A unique developer whose committing email is linked to a confirmed SCM account, such as a GitHub identity. Multiple committing emails linked to the same SCM account are counted as one in the license consumption count. * **Unverified**: The committing email could not be associated with an SCM identity. This also happens when branches are scanned in CI or CLI mode, where the scan has no access to SCM APIs to resolve identities. ### Organizations that need attention The **Organizations that need attention** list shows organizations with unverified contributors. Verify these contributors to get an accurate license consumption count and resolve developers who would otherwise be counted incorrectly. For projects scanned with scheduled, agentless scans, Endor Labs verifies contributors automatically through SCM APIs. Projects scanned through the CLI or in CI need manual verification. To verify contributors: 1. Click the vertical three dots on the organization you want to verify and select **Verify contributors**. 2. Enter the access token with the required permissions. See [Supported SCM platforms and access tokens](#supported-scm-platforms-and-access-tokens) to learn more. 3. Click **Verify**. Verification runs in the background and refreshes the status in the list and the contributor count. If verification fails, the status shows an error. Review the error detail for the reason and how to resolve it. Verification error The status indicator may show failure even if some projects in the organization are verified but others aren't, due to permission or other issues. Download the CSV to see which projects failed, fix the cause, and verify again. Some contributors remain unverified even after verification, such as those whose committing emails are local machine addresses, CI/CD bot commits, or emails with typos in the Git configuration. If unverified contributors count remains but no organizations appear in the list, their committing emails could not be linked to any SCM identity. Download the CSV to identify these contributors. Contributing developers only ### Supported SCM platforms and access tokens To verify contributors, use an access token with the minimum permissions required for your SCM platform, as shown in the following table. ## Scan credits Your license includes scan credits for each contributing developer, which pool across your contract term. The page shows your scan credit usage and total scan credit pool. Each PR scan, monitored branch scan, and default branch scan above the allowed limit counts against the scans permitted by your contract plan. For per-seat allocations, credit pooling, and overage, see [Endor Labs licenses](/introduction/licenses#entitlements-and-limits). ## Frequently asked questions Your access token is invalid, expired, or missing permissions. Generate a new token with the [required permissions](#supported-scm-platforms-and-access-tokens) and verify again. Verification succeeded for some projects and failed for others. Download the CSV to see which projects failed, fix the cause, and verify again. No. Endor Labs automatically filters known bots, such as Dependabot, Renovate, and GitHub Actions, so they are not counted. Other bots may still appear in the contributor list. Contact your account team for additional information. Endor Labs clears the token after verification and does not store it. Enter it again each time you verify. The count reflects commits from the past 90 days and refreshes periodically. Contributors who have not committed in that window drop out automatically. Once. A developer who commits to multiple projects counts only once toward your license consumption. No. Scans continue and any overage appears in your usage. Contact your account team to add more credits. Their commit emails are not linked to any SCM account, such as local machine addresses, bot commits, or typos in the Git configuration. Download the CSV to find them, then link the email to the SCM account or correct the Git configuration. Contact your account team for additional information. # Set up namespaces Source: https://docs.endorlabs.com/platform-administration/namespaces/index Use namespaces to organize your projects logically and define hierarchy. Namespaces in Endor Labs define a way to group projects and create logical partitions in an organization based on organizational units, business units, project requirements, or teams. Using namespaces, administrators can: * Define hierarchy and control access to project resources within a namespace. * Establish policy governance by defining the rules of engagement and setting different or same guardrails across namespaces. ## Namespaces in an organization In Endor Labs, you can partition each tenant into multiple namespaces and further divide each namespace into sub-namespaces called child namespaces. Each namespace has its own authorization rules and integrations. Child namespaces inherit settings, policies, and features from their parent namespace but can also define their own authorization rules, policies, and configurations. This structure helps organizations model hierarchical environments, with each level managing its own access controls and operational settings. When you access your tenant, Endor Labs includes data from all child namespaces in the dashboard by default, such as vulnerabilities, dependencies, packages, and more. In **namespace**, toggle the setting to **All child namespaces excluded** to exclude child namespaces and view data and metrics for only the selected namespace. Namespaces toggle When you sign in to Endor Labs for the first time, create a tenant for your organization, such as `abccorp`. * Now you can create logical separations in the form of namespaces for different business units in your organization, such as Security Business Unit (`security-bu`), Datacenter Business Unit (`datacenter-bu`), and Orchestration Agent Business Unit (`orchestration-agent-bu`), inside your main tenant `abccorp`. * You can further partition the Security Business Unit into sub-namespaces, such as the Development team (`dev-team`), Finance Team (`finance-team`), and Testing Team (`testing-team`). Namespaces Example * There can be multiple namespaces within `abccorp`. For example, the `dev-team` namespace that hosts projects belonging to the development team of the Security Business Unit and the `test-team` namespace that hosts projects belonging to the testing team of the Security Business Unit. ### Use namespaces for authorization Large enterprises with multiple business units, teams, or groups can assign different namespaces to different groups and apply authorization policies that restrict access to specific groups. This ensures least privilege access to critical information is available in the organization. Organizations can also provision namespaces to provide read access to security teams in specific namespaces while they provide write access to AppSec teams for managing policies. * Create an authorization policy giving users in the development team of the security business unit permissions to scan their projects. Users from group `@developers.abccorp.ai` can have code scanner permissions for the namespace `dev-team`. * Users from group `@applicationsecurity.abccorp.ai` can have policy editor permissions for the namespace `dev-team`. The developers can scan the code, and the application security professionals can define the policies for code compliance. * The application security professionals can also choose to define the policies at the tenant level `abccorp` and choose to apply the same policies to all the child namespaces. This way, they won't need to create policies individually for every child namespace. The development team inherits the policies from the organization and won't be able to modify them. They can, however, add additional policies that are specific to engineering to their namespace `dev-team` and define specific rules and conditions applicable only to them. ### Use namespaces for policy governance Administrators can use namespaces effectively for policy governance and make sure that teams in their organization adhere to industry-wide policy standards enforcing compliance. Let us assume that the application security team in `ABCcorp` wants to define organization-wide rules for code compliance, vulnerability management, and secret detection. They also need Jira tickets filed for all cases. The application security engineers can create the following objects at the `ABCcorp` tenant level and propagate these objects to all the namespaces under `abccorp` so that it applies to the entire organization. * Define action policy to break the build when scans detect critical vulnerabilities. * Define action policy to warn the user of detected code compliance misconfigurations. * Define action policy to break the build when scans detect valid secret tokens in their code. * Create Jira tickets and notify the appropriate team to take remediation measures. ## Create a namespace To create a namespace in your tenant: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Namespaces**. 3. Click **New Namespace**. 4. Enter a title and description for the namespace. The title can have a maximum of 32 characters and must contain only lowercase letters (a-z), numbers (0-9), and characters (\_-). 5. Enter tags that you want to associate with this namespace. Tags can have a maximum of 63 characters and must contain letters (A-Z), numbers (0-9), and characters (=@\_.-). ## Edit a namespace You can choose to modify the description of a namespace or include tags for it. You can't modify its title after you create a namespace. To edit details of a namespace in your tenant: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Namespaces**. 3. Choose the namespace and click **Edit**. 4. Edit the description or include tags for the namespace. 5. Click **Update Namespace**. ## Delete a namespace Deleting a namespace permanently deletes all its child namespaces and its projects. To delete a namespace: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Namespaces**. 3. Choose the namespace and click **Delete**. 4. Select and confirm the deletion. 5. Click **Delete Namespace**. ## Data propagation from parent to child namespaces Data propagation defines how child namespaces inherit data from their parent namespace. * **Finding Policies** - When you create a namespace, all the finding policies in the parent are **inherited** by the child namespaces. Any new finding policy you create in the parent, you can choose to apply it to the child namespaces by selecting **Propagate this policy to all child namespaces**. * **Action Policies** - When you create a namespace, all the action policies in the parent are **inherited** by the child namespaces. Any new action policy you create in the parent, you can choose to apply it to the child namespaces by selecting **Propagate this policy to all child namespaces**. * **Remediation Policies** - When you create a namespace, all the remediation policies in the parent are **inherited** by the child namespaces. Any new remediation policy you create in the parent, you can choose to apply it to the child namespaces by selecting **Propagate this policy to all child namespaces**. * **Exception Policies** - When you create a namespace, all the exception policies in the parent are **inherited** by the child namespaces. Any new exception policy you create in the parent, you can choose to apply it to the child namespaces by selecting **Propagate this policy to all child namespaces**. * **Package Manager Integrations** - Package manager integrations of the parent are **not inherited** by the child namespaces. Any new package manager integration you create in the parent, you can choose to apply them to the child namespaces by selecting **Propagate this package manager to all child namespaces**. * **Integrations** - Integrations in the parent are **not inherited** by the child namespaces. * **Authorization Policies** - Authorization policies of the parent are **inherited** by all its child namespaces. You can choose to group the authorization policies of the child namespaces in their parent namespace and manage them easily. * **Secret Rules** - You can choose to apply custom secret rules created in the parent to its child namespaces by selecting **Propagate this rule to all child namespaces**. * **API Key** - You can create an API key in a namespace and select **Propagate this rule to all child namespaces** to apply the key to all child namespaces. ## Tenant and namespace terminologies Tenant is the top-level entity under which you can create namespaces and child namespaces. To denote a namespace, always use its fully qualified name. Fully qualified name for a namespace is in the format `tenantname.namespacename`, and child namespace is in the format `tenantname.namespacename.childnamespacename`. * In this example, the tenant is `abccorp` and its child namespaces are `abccorp.security-bu`, `abccorp.datacenter-bu`, and `abccorp.agent-bu`. The child namespaces of `abccorp.security-bu` are `abccorp.security-bu.dev-team`, `abccorp.security-bu.testing-team`, and `abccorp.security-bu.finance-team`. * Consider a tenant named `acme` with a child namespace `dev`, which in turn has a child namespace `app`. The fully qualified namespace for `app` is `acme.dev.app`. # Action policies Source: https://docs.endorlabs.com/platform-administration/policies/action-policies/index Learn about action policies and how to use them. Action policies define the workflows that are triggered when the application encounters a given set of criteria (a.k.a. findings). For example, action policies can be used to: * Configure the behavior of scan in a CI/CD based environment. * Set up custom ticketing workflows. * Set up custom messaging workflows. ## Manage action policies You can view, enable, clone, disable, edit, or delete your Endor Labs action policies. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Action Policies**. 3. The preset filters help you locate the action policies that matter most to you. Select a category to narrow down and focus on the relevant policies. 4. Use the search bar to search for a policy. 5. Enable or disable a policy using the toggle. 6. Select **Hide Disabled** to hide policies that are not enabled. 7. Select **Hide Warnings** to hide policies that are not blocking or notifications. 8. To delete a policy, click on the vertical three dots and select **Delete Policy**. 9. To edit a policy, click on the vertical three dots and select **Edit Policy**. Action policies ## View policy details 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Action Policies** to view the list of action policies. 3. Select a policy you want to review and click **View Details**. You can see the policy’s description, scope, and metadata. You can review the severity, finding categories, explanatory details, remediation steps and the Rego rules that implement the policy logic. View action policy details ## Create an action policy from template You can create an action policy in Endor Labs to perform a given action when a given set of conditions are met. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Action Policies**. 3. Click **Create Action Policy** to create a new action policy. 4. First, you must **Define a Policy**. 5. Choose a **Template Category** from the list. 6. Choose a **Policy Template** from the list and define the criteria for the action. See [Action policy templates](/platform-administration/policies/action-policies/templates) for more information. 7. Next, **Choose an Action** to take when the policy criteria are met. * Choose **Enforce Policy** to define the behavior of endorctl scans. * A **Warn** enforcement action will warn the user when the policy criteria are met by letting them know which findings violate the policy. **Warn** enforcement actions will only notify users of policy violations and will still return a 0 exit code in CI/CD environments, which won't fail a job. However, it is possible to configure the scan to return a non-zero (129) exit code for policy warnings by setting the `--exit-on-policy-warning` flag. * A **Break the Build** enforcement action will return a non-zero (128) exit code, which will fail the job. This action will inform the user which findings violate the policy as part of the scan. * Choose **Send Notification** to create a ticket or send a custom message to an integrated notification system. * A **Notification Target** must be set to send a notification. A notification target may be defined as a notification integration. For more information, see [Endor Labs integrations](/integrations). * From **Select aggregation type**, choose how findings are grouped into notifications. * Choose **None (Notify for each Finding)** to trigger a separate notification for each finding. * Choose **Project** to trigger a single notification for all findings. * Choose **Dependency** to trigger multiple notifications for every dependency. * Choose **Dependency per Package Version** to trigger multiple notifications for unique combinations of dependency and package. For more information, see [Aggregation types for notifications](#aggregation-types-for-notifications). Notifications are only processed for monitored branches, not for pull requests. 8. You can **Assign Scope** to the action policy by specifying what projects the policy has to scan. * In **Inclusions**, enter the projects and the tags of the projects that you want to scan. * In **Exclusions**, enter the projects and the tags of the projects that you do not want to scan. Exclusions take precedence over the inclusions, in case of a conflict. * Click the link to view the projects included in the action policy scan. * Click **Add project tag to these projects** and enter a tag for the selected projects. Click **Save Tags** to apply it or **Reset Tags** to discard changes. * You can set custom tags for your projects from **Projects** > **Settings** > **Custom Tags**. See [Tagging projects](/platform-administration/policies/tagging-projects) for more information about creating project tags. 9. **Name Your Action Policy**. * Enter a human readable **Name** for your action policy. * Enter a **Description** for your action policy that describes what it does. * Enter any **Policy Tags** that you want to associate with your policy. Tags can have a maximum of 63 characters and can contain letters, numbers, and characters `=`, `@`, `_`, and `-`. 10. By default, a policy applies to the current namespace and all its child namespaces. To limit it to the current namespace, clear **Propagate this policy to all child namespaces**. 11. Click **Create Action Policy**. The policy will be enabled by default. To block pull requests with an action policy, set the enforcement action to **Break the Build** and mark the Endor Labs check as a required status check in your source control manager. See [Block pull requests on findings](/scan/pr-scans#block-pull-requests-on-findings) for the end-to-end workflow. ## Create an action policy from scratch Write an action policy from scratch using the [OPA Rego policy language](https://www.openpolicyagent.org/docs/latest/policy-language/). 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Action Policies**. 3. Click **Create Action Policy** 4. Choose **From Scratch** to author an action policy 5. Enter the Rego rule for the policy in **Rego Definition**. For instance, the following Rego rule identifies all repository version findings that are not present in the baseline. Action policies should only operate on Findings. For more information about findings, see the [Finding resource kind documentation](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#finding). ```rego theme={null} package examples match_baseline(finding) { some i data.baseline.Finding[i].meta.description == finding.meta.description } match_repo_version_finding[result] { some i data.resources.Finding[i].meta.parent_kind == "RepositoryVersion" not match_baseline(data.resources.Finding[i]) result = { "Endor": { "Finding": data.resources.Finding[i].uuid } } } ``` 6. Enter the OPA **Query Statement** for the rule in the following format: `data..`. For the example above the query statement is `data.examples.match_repo_version_finding` 7. Select the **Resource Kinds** required to evaluate the policy. For the example above the required resource kind is `Finding`. The requested resource kind records for the current scan are made available to the Rego code under `data.resources.`. The corresponding baseline records are available under `data.baseline.`. Note: Action policies should only operate on Findings 8. Continue with steps 7-11 above under [Create an action policy from template](#create-an-action-policy-from-template) Rescan the project to apply the newly created action policy and update the findings. ### Expected output format All action policies must list the matching Finding UUID under "Endor" in the following format. ```rego theme={null} foo[result] { result = { "Endor": { Finding: } } } ``` ### Validate policy The application verifies the Rego syntax and query statement before creating the policy. However, the logic cannot be fully validated without input data. See the [endorctl validate policy](/developers-api/cli/commands/validate) command for details on how to validate a custom policy and inspect the matches returned for a given project. ### Baseline data For action policies that are used to comment on, or block, PR scans you often only want to trigger the policy for findings that are not present in the baseline. The baseline data for the requested resource kinds is available under `data.baseline.`. Here are some examples of how to implement a function called `match_baseline` that returns true if a given finding also exists in the baseline. As in the [example above](#create-an-action-policy-from-scratch), you can then call `not match_baseline(data.resources.Finding[i])` to filter out findings that are not unique to the PR scan. Any additional resource kinds, for example `DependencyMetadata`, must be added to the list of requested [**Resource Kinds**](#create-an-action-policy-from-scratch). Baseline data is only loaded for action policies with one of the **Enforce Policy** actions (**Warn** or **Break the Build**). It is not loaded for any other policy types. ```rego expandable theme={null} match_baseline(finding) { finding.meta.parent_kind == "PackageVersion" some i data.baseline.Finding[i].meta.description == finding.meta.description data.baseline.Finding[i].spec.target_dependency_package_name == finding.spec.target_dependency_package_name } match_baseline(finding) { finding.meta.parent_kind == "PackageVersion" some i, j data.baseline.DependencyMetadata[i].meta.name == finding.spec.target_dependency_package_name data.resources.DependencyMetadata[j].meta.name == finding.spec.target_dependency_package_name data.baseline.DependencyMetadata[i].spec.importer_data.package_name == data.resources.DependencyMetadata[j].spec.importer_data.package_name data.baseline.DependencyMetadata[i].spec.dependency_data.reachable == data.resources.DependencyMetadata[j].spec.dependency_data.reachable } match_baseline(finding) { finding.meta.parent_kind == "RepositoryVersion" some i data.baseline.Finding[i].meta.description == finding.meta.description } match_baseline(finding) { finding.meta.parent_kind == "Repository" some i data.baseline.Finding[i].meta.description == finding.meta.description } match_baseline(finding) { finding.spec.finding_categories[_] == "FINDING_CATEGORY_SECRETS" some i data.baseline.Finding[i].spec.extra_key == finding.spec.extra_key count(data.baseline.Finding[i].spec.finding_metadata.source_policy_info.results) == count(finding.spec.finding_metadata.source_policy_info.results) } match_baseline(finding) { finding.spec.finding_categories[_] == "FINDING_CATEGORY_SAST" some i data.baseline.Finding[i].spec.extra_key == finding.spec.extra_key count(data.baseline.Finding[i].spec.finding_metadata.source_policy_info.results) == count(finding.spec.finding_metadata.source_policy_info.results) } ``` ## Aggregation types for notifications Aggregation types for notifications streamline the organization and management of findings for efficient workflow. By default, all project findings are included in a single notification. With the option to select aggregation types, notifications can be tailored to specific criteria based on dependencies. This customization simplifies developer actions and enhances productivity. Endor Labs enables you to choose the following notification aggregation types, each offering distinct benefits. * **None (Notify for each Finding)**: Select **None (Notify for each Finding)** to create a separate notification for each finding in the project. * **Project**: (Default) Select **Project** to create a single notification for all project findings. * **Dependency**: Select **Dependency** to create separate notifications for each dependency in a project. * **Dependency per Package Version**: Select **Dependency per Package Version** to create separate notifications for each package in a project. Sub-tasks are created for each unique combination of dependency and package. ### Example For Jira integration notifications, a parent ticket is created with the selected issue type, either `Task` or `Bug`. The parent ticket includes the project name. Each identified dependency is grouped under a dedicated sub-ticket. The sub-ticket includes both the project name and dependency name. Findings without any dependency are grouped in a separate sub-ticket. During future scans, the existing sub-ticket status is updated or resolved. If a new dependency is found, a new sub-ticket is created. # Action policy templates Source: https://docs.endorlabs.com/platform-administration/policies/action-policies/templates/index Learn about the predefined action policy templates and how to customize them. Endor Labs provides the following action policy templates that you can use to quickly create action policies. Each policy template provides parameters to help you customize the conditions under which a policy action takes place. All action policy templates automatically only match new findings for PR scans, assuming that there is a baseline that the scan results can be compared to. If the finding already exists in the baseline, then it is not considered to be a match. See [PR baseline](/developers-api/cli/commands/scan#pull-request-ci-flags) and [PR comments](/scan/pr-scans/pr-comments#enable-pr-comments) to learn more. The following template categories are available: * [Container](#container) * [GitHub Actions](#github-actions) * [Malware](#malware) * [SAST](#sast) * [SCA](#sca) * [Secrets](#secrets) * [Security Review](#security-review) * [Vulnerabilities](#vulnerabilities) ## Container Use these templates to define actions for findings related to container images, including vulnerabilities in base images, installed packages, and container configurations. ### Containers Matches container findings for vulnerabilities that meet specific parameters. The following table describes the parameters. ### Custom (Advanced) Allows you to define a custom action policy based on the attributes of the finding. The following table describes the parameters. #### Finding categories Findings are classified into one or more of the following categories: #### Finding types Findings are classified into the following types when the packages scanned include: ## GitHub Actions Use this template to match findings from GitHub Actions workflows, such as risky action usage or supply chain issues in your CI configuration. Ensure the relevant [GitHub Action finding policies](/platform-administration/policies/finding-policies/github-action-policies) are enabled so Endor Labs raises these findings. The following table describes the parameters. ## Malware Allows you to define the action policy to apply when a malware finding is detected, depending on its status, relationship to root packages, and ecosystem. The following table describes the parameters. ## SAST Allows you to define the action taken when a SAST finding is raised. ## SCA Use these templates to define actions for Software Composition Analysis (SCA) findings, including vulnerabilities, outdated dependencies, unmaintained packages, license risks, and other issues in your open-source dependencies. ### Containers Matches container findings for vulnerabilities that meet specific parameters. The following table describes the parameters. ### Custom (Advanced) Allows you to define a custom action policy based on the attributes of the finding. The following table describes the parameters. ### Malware Allows you to define the action policy to apply when a malware finding is detected, depending on its status, relationship to root packages, and ecosystem. The following table describes the parameters. ### Outdated Releases Matches findings based on older versions of software or dependencies and are not actively updated. The following parameters are supported: ### Recently Released Dependencies (cooldown) Matches findings for recently released dependencies. Supported configuration parameters for this action policy template are: ### Unmaintained Dependencies Matches findings based on dependencies that are no longer maintained or may have reached end-of-life. The following parameters are supported: ### Unpinned Direct Dependencies Matches findings based on direct dependencies that do not have a version or a range of versions specified. Supported configuration parameters for this action policy template are: ### Unreachable Direct Dependencies Matches findings based on dependencies that are not directly used or called within a project. Supported configuration parameters for this action policy template are: ### Vulnerabilities Matches findings that are vulnerabilities that meet specific parameters. The following table describes the parameters. ## Secrets Allows you to define the action taken when a leaked secret is detected based on the validation status of the secret. ## Security Review Use these templates to define actions for security review findings that require manual assessment or additional analysis before taking action. Match security review findings. The following parameters are supported: ## Vulnerabilities Use these templates to define actions for vulnerability findings, including CVEs, security advisories, and known exploits in your dependencies based on severity, exploitability, and fix availability. ### Containers Matches container findings for vulnerabilities that meet specific parameters. The following table describes the parameters. ### Custom (Advanced) Allows you to define a custom action policy based on the attributes of the finding. The following table describes the parameters. ### Vulnerabilities Matches findings that are vulnerabilities that meet specific parameters. The following table describes the parameters. # Exception policies Source: https://docs.endorlabs.com/platform-administration/policies/exception-policies/index Learn about exception policies and how to use them. Exception policies define the conditions for applying an exception to a finding. When an exception is applied to a finding, it is tracked as an exception and action policies do not apply to it. Findings with exceptions are filtered out from Endor Labs reports by default. For example, exception policies can be used to: * Exclude a specific finding for a specific package from build breaking policies. * Exclude specific vulnerabilities that are accepted across your organization. * Mark an identified issue as a false positive. ## Manage exception policies You can view, enable, clone, disable, edit, or delete your Endor Labs exception policies. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Exception Policies**. 3. The preset filters help you locate the exception policies that matter most to you. Select a category to narrow down and focus on the relevant policies. 4. Use the search bar to search for a policy or click **Create Exception Policy**. 5. Enable or disable a policy using the toggle. 6. To delete a policy, click the vertical three dots and select **Delete Policy**. 7. To edit a policy, click on the vertical three dots and select **Edit Policy**. Exception policies You can edit the exception policy name from the findings detail drawer if you have admin permissions. This change updates the exception policy name for all findings that reference it. ## View policy details 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Exception Policies** to view the list of exception policies. 3. Select a policy you want to review and click **View Details**. You can see the policy’s description, scope, and metadata. You can review the severity, finding categories, explanatory details, remediation steps and the Rego rules that implement the policy logic. View exception policy details ## Create an exception policy from a template You can create an exception policy in Endor Labs to apply an exception to a finding when a given set of conditions are met. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Exception Policies**. 3. Click **Create Exception Policy**. 4. In **Define Exception Criteria**, choose a **Template Category** from the list. 5. Choose a **Policy Template** from the list and define the criteria for the exception. See [exception policy templates](/platform-administration/policies/exception-policies/templates) to choose a template and define the criteria for the exception. 6. You can also enter exception tags to findings that match the exception policy. 7. Next, you must **Choose a Reason** for your exception and set an expiration time for the exception. * Select from the following reasons why you are applying this exception: * **In Triage**: The finding is still being triaged for more information. * **False Positive**: The finding is a false positive. * **Risk Accepted**: The risk associated with the finding is accepted. * **Resolved**: The issue has been resolved. * **Other**: Another reason applies for this exception. * Select when the exception should expire. Options include `30`, `60`, `90` days, or `Never`. 8. You can **Assign Scope** to the exception policy by specifying what projects the policy has to scan. * In **Inclusions**, enter the projects and the tags of the projects that you want to scan. * In **Exclusions**, enter the projects and the tags of the projects that you do not want to scan. Exclusions take precedence over the inclusions, in case of a conflict. * Click the link to view the projects included in the exception policy scan. * Click **Add project tag to these projects** and enter a tag for the selected projects. Click **Save Tags** to apply it or **Reset Tags** to discard changes. * You can set custom tags for your projects from **Projects** > **Settings** > **Custom Tags**. See [Tagging projects](/platform-administration/policies/tagging-projects) for more information about creating project tags. 9. Finally, you must **Name Your Exception Policy**. * Enter a human-readable **Name** for your exception policy. * Enter a **Description** for your exception policy that explains its function. * Enter any **Policy Tags** that you want to associate with your policy. Tags can have a maximum of 63 characters and can contain letters, numbers, and characters = @ \_ -. 10. **Advanced**: When you define a policy, it applies to the current namespace and all its child namespaces. To prevent the policy from being applied to any child namespace, click **Advanced** and deselect **Propagate this policy to all child namespaces**. 11. Click **Create Exception Policy**. The policy is enabled by default. When creating exceptions for a specific package, make sure to not include the version of the package in the package name template parameter. Adding the version to the name can result in the exception not applying to a newly released version of the package. ## Create an exception policy from scratch Write an exception policy from scratch using the [OPA Rego policy language](https://www.openpolicyagent.org/docs/latest/policy-language/). You can create an exception policy in Endor Labs to apply an exception to a finding when a given set of conditions are met. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Click on the **Exception Policies** tab. 3. Click **Create Exception Policy** to create a new exception policy 4. First, choose **From Scratch** to author an exception policy under **Define Exception Criteria**. 5. Enter the Rego rule for the policy in **Rego Definition**. For example, the following Rego rule recognizes a set of 3 vulnerabilities acknowledged by an organization, with an organization-wide exception. For more information about findings, see the [Finding resource kind documentation](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#finding). ```bash theme={null} package exceptions match_vuln_id(finding, ids) { finding.spec.finding_metadata.vulnerability.meta.name = ids[_] } match_vuln_id(finding, ids) { finding.spec.finding_metadata.vulnerability.spec.aliases[_] = ids[_] } match_finding[result] { some i ids := ["CVE-2020-10683", "CVE-2019-0231", "CVE-2017-0144"] match_vuln_id(data.resources.Finding[i], ids) result = { "Endor" : { "Finding" : data.resources.Finding[i].uuid } } } ``` 6. Enter the OPA **Query Statement** for the rule in the following format: `data..`. For the example above the query statement is `data.exceptions.match_finding`. 7. Select the **Resource Kinds** required to evaluate the policy. For the example above, the required resource kind is `Finding`. The requested resource kind records for the current scan are made available to the Rego code under `data.resources.`. 8. You can also enter exception tags to findings that match the exception policy. 9. Next, you must **Choose a Reason** for your exception and set an expiration time for the exception. * Select from the following reasons why you are applying this exception: * **In Triage**: The finding is still being triaged for more information. * **False Positive**: The finding is a false positive. * **Risk Accepted**: The risk associated with the finding is accepted. * **Resolved**: The issue has been resolved. * **Other**: Another reason applies for this exception. * Select when the exception should expire. Options include 30, 60, 90 days, or Never. 10. **Assign Scope** for which this exception policy should apply. Scopes are defined by the tags assigned to a project. * In **Inclusions**, enter the tags of the projects that you want to apply an exception to. * In **Exclusions**, enter the tags of the projects that you do not want to apply an exception to. Exclusions take precedence over the inclusions, in case of a conflict. * Click the link to view the projects included in the exception policy. * See [Tagging projects](/platform-administration/policies/tagging-projects) for more information about creating project tags. 11. Finally, you must **Name Your Exception Policy**. * Enter a human-readable **Name** for your exception policy. * Enter a **Description** for your exception policy that explains its function. * Enter any **Policy Tags** that you want to associate with your policy. Tags can have a maximum of 63 characters and can contain letters, numbers, and characters = @ \_ -. 12. **Advanced**: When you define a policy, it applies to the current namespace and all its child namespaces. To prevent the policy from being applied to any child namespace, click **Advanced** and deselect **Propagate this policy to all child namespaces**. 13. Click **Create Exception Policy**. The policy is enabled by default. Rescan the project to apply the newly created exception policy and update the findings. ### Expected output format All exception policies must list the matching Finding UUID under "Endor" in the following format. ```bash theme={null} foo[result] { result = { "Endor": { Finding: } } } ``` ### Validate policy The application verifies the Rego syntax and query statement before generating the policy. However, the logic cannot be validated without input data. See the [endorctl validate policy](/developers-api/cli/commands/validate) command for instructions on validating a custom policy and inspecting the matches returned for a specific project. # Exception policy templates Source: https://docs.endorlabs.com/platform-administration/policies/exception-policies/templates/index Learn about the predefined exception policy templates and how to customize them. Endor Labs provides the following exception policy templates that you can use to quickly create exception policies. Each exception policy template provides parameters to help you customize the conditions under which an exception is applied. The following template categories are available: * [Container](#container) * [SCA](#sca) * [Vulnerabilities](#vulnerabilities) * [Secrets](#secrets) * [Malware](#malware) * [SAST](#sast) ## Container Use these templates to define exceptions for findings related to container images, including vulnerabilities in base images, installed packages, and container configurations. ### Common Define exceptions for common use cases such as: * Exclude a specific finding, for a specific package, for a specific dependency. * Exclude all findings for a specific dependency. * Exclude all findings for a specific package. * Exclude all vulnerabilities that do not have a patch available. The following table describes the parameters. ### Custom (Advanced) Define exceptions based on custom criteria that are less common for findings. For example, you can exclude all findings generated based on approximate scans for a specific ecosystem. The following table describes the parameters. ### Vulnerabilities Define exceptions for vulnerabilities findings. ## SCA Use these templates to define exceptions for Software Composition Analysis (SCA) findings, including vulnerabilities, outdated dependencies, unmaintained packages, license risks, and other issues in your open-source dependencies. ### Common Define exceptions for common use cases such as: * Exclude a specific finding, for a specific package, for a specific dependency. * Exclude all findings for a specific dependency. * Exclude all findings for a specific package. * Exclude all vulnerabilities that do not have a patch available. The following table describes the parameters. ### Custom (Advanced) Define exceptions based on custom criteria that are less common for findings. For example, you can exclude all findings generated based on approximate scans for a specific ecosystem. The following table describes the parameters. ### Vulnerabilities Define exceptions for vulnerabilities findings. ### Malware Define exceptions for malware findings. ## Secrets Define exceptions for secrets findings. ## Malware Define exceptions for malware findings. ## SAST Define exceptions for SAST findings. ## Vulnerabilities Use these templates to define exceptions for vulnerability findings, including CVEs, security advisories, and known exploits in your dependencies. ### Common Define exceptions for common use cases such as: * Exclude a specific finding, for a specific package, for a specific dependency. * Exclude all findings for a specific dependency. * Exclude all findings for a specific package. * Exclude all vulnerabilities that do not have a patch available. The following table describes the parameters. ### Custom (Advanced) Define exceptions based on custom criteria that are less common for findings. For example, you can exclude all findings generated based on approximate scans for a specific ecosystem. The following table describes the parameters. ### Vulnerabilities Define exceptions for vulnerabilities findings. # Container policies Source: https://docs.endorlabs.com/platform-administration/policies/finding-policies/container-policies/index Learn about the predefined finding policy templates for containers. Endor Labs provides the following policies to help assess and improve the security posture of your container images. This policy scans container images to detect operating system dependencies or components that have reached end of life (EOL). Endor Labs disables this policy by default. Enable it in **Finding Policies**. If a dependency reaches EOL after the initial scan, containers do not need to be re-scanned. The analytics scan automatically detects the change and raises a finding without requiring a rescan. This policy detects end of life status only for OS-level packages and components. Endor Labs provides the following container image finding policy template to detect if a base image is not permitted by an organization. See [Finding Policies](/platform-administration/policies/finding-policies/container-policies/..) for details on how to create policies from policy templates. # GitHub Action policies Source: https://docs.endorlabs.com/platform-administration/policies/finding-policies/github-action-policies/index Learn about the out-of-the-box finding policies for GitHub Actions. Endor Labs provides the following out-of-the-box policies that help you assess the security posture of GitHub Actions used in your software delivery process. Findings from these templates appear after you enable [GitHub Actions scanning](/scan/github-actions). * [Policies for Repository Security Posture Management (RSPM) in GitHub](#policies-for-rspm). * [Policies for evaluating configuration settings in workflow file](#policies-for-assessing-configuration-settings-in-workflow-files). See [Finding policies](/platform-administration/policies/finding-policies) for details on how to **enable**, **disable**, or **edit** out-of-the-box policies. To automate responses to these findings, such as failing checks, posting pull request comments, or sending notifications, create an action policy using the [GitHub Actions policy template](/platform-administration/policies/action-policies/templates#github-actions). ## Policies for RSPM ## Policies for assessing configuration settings in workflow files # Finding policies Source: https://docs.endorlabs.com/platform-administration/policies/finding-policies/index Learn about finding policies and how to use them. All findings are enabled, disabled and/or customized via policies. There are three types of Finding Policies: 1. [Open-source software management](/platform-administration/policies/finding-policies/oss-policies) - Enable or disable findings for Vulnerabilities and Malicious Packages, Outdated Dependencies, Recently Released Dependencies, Unmaintained Dependencies, Unpinned Direct Dependencies, Unused Direct Dependencies, License Risks 2. [Repository security posture management configuration](/platform-administration/policies/finding-policies/managing-scm-configuration) - Enable, disable, or customize out-of-the-box policies repository security posture management (RSPM) 3. [Custom](#custom-finding-policies) - Create custom policies from scratch or from pre-defined policy templates ## Manage finding policies You can view, enable, disable, edit, upgrade, or delete your Endor Labs finding policies. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Finding Policies** to view the list of finding policies. 3. The preset filters help you locate the finding policies that matter most to you. Select a category to narrow down and focus on the relevant policies. 4. Enter text in the search bar to find a policy by name or keyword. 5. Use the toggle next to a finding policy to enable or disable the finding policy. 6. Select **Hide Disabled** to hide policies that are not enabled. 7. Use **Finding Level** to filter policies by **Critical**, **High**, **Medium**, or **Low**. 8. To edit a policy, click on the vertical three dots and select **Edit**. 9. To delete a policy, click on the vertical three dots and select **Delete**. The findings associated with the policy are not deleted. finding policy ### Upgrade a finding policy Upgrades are available when there are changes to a policy, such as new fields, parameters, tags, or updates to the Rego code. After upgrading a policy, you can't revert it to its previous version. You can upgrade a policy to the latest template version in any of the following two ways: * Click on the vertical three dots and select **Upgrade** and click **Upgrade Policy**. * Click on **Upgrade Available**, review the release notes and click **Upgrade Policy**. You can enable automatic policy upgrades from the **Policies & Rules** system settings. See [configure policy settings](/platform-administration/configure-system-settings#configure-policy-settings) for more information. You can upgrade finding policies if you have admin permissions. ## View policy details 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Finding Policies** to view the list of finding policies. 3. Select a policy you want to review and click **View Details**. You can see the policy’s description, scope, and metadata. You can review the severity, finding categories, explanatory details, remediation steps and the Rego rules that implement the policy logic. View finding policy details ## Custom finding policies Create custom finding policies to identify additional issues based on the needs of your organization. For example, you can create license violation policies to define the behavior for missing, unknown, problematic, or incompatible licenses. You can permit or restrict packages with certain license types. Endor Labs provides finding policy templates for multiple use cases: * [License management](/platform-administration/policies/finding-policies/license-policies) * [Secret detection](/platform-administration/policies/finding-policies/secret-policies) ### Create a finding policy from template Create a finding policy from a pre-defined Endor Labs template. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Click **Create Finding Policy**. 3. Choose **From Template** to create a finding policy from template. 4. Choose a **Template Category** from the list. 5. Choose a **Policy Template** from the list. The template details are pre-filled with recommended values on the form. 6. Endor Labs pre-populates **Severity**, **Summary**, **Explanation**, **Remediation**, **Finding Name**, and **Finding Categories** with recommended values. You can modify these fields except **Finding Categories**. 7. In **Finding Custom Tags**, enter custom tags that you want to associate with the findings of this policy. Custom tags can have a maximum of 255 characters and can contain letters, numbers, and characters = @ \_ -. These are different and separate from the system defined finding tags. 8. You can **Assign Scope** to the finding policy by specifying what projects the policy has to scan. * In **Inclusions**, enter the projects and the tags of the projects that you want to scan. * In **Exclusions**, enter the projects and the tags of the projects that you do not want to scan. Exclusions take precedence over the inclusions, in case of a conflict. * Click the link to view the projects included in the finding policy scan. * Click **Add project tag to these projects** and enter a tag for the selected projects. Click **Save Tags** to apply it or **Reset Tags** to discard changes. * You can set custom tags for your projects from **Projects** > **Settings** > **Custom Tags**. See [Tagging projects](/platform-administration/policies/tagging-projects) for more information about creating project tags. 9. **Name Your Finding Policy**. * Enter a human readable **Name** for your finding policy. * Enter a **Description** for your finding policy that describes what it does. * Enter any **Policy Tags** that you want to associate with your policy. Tags can have a maximum of 255 characters and can contain letters, numbers, and characters = @ \_ -. 10. **Advanced**: When you define a policy you do so for the current namespace and all child namespaces. If you do not want the policy to be applied to any child namespaces, click **Advanced** and deselect **Propagate this policy to all child namespaces**. 11. Click **Create Finding Policy**. The policy will be enabled by default. Rescan the project to apply the newly created finding policy and update the findings. ### Create a finding policy from scratch Write a finding policy from scratch using the [OPA Rego policy language](https://www.openpolicyagent.org/docs/latest/policy-language/). 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Click **Create Finding Policy**. 3. Choose **From Scratch** to author a finding policy from scratch. 4. Enter the Rego rule for the policy in **Rego Definition**. For instance, the following Rego rule identifies dependencies with an Endor Labs overall score lower than 7. ```bash theme={null} package examples match_package_version_score[result] { some i data.resources.Metric[i].meta.name == "package_version_scorecard" data.resources.Metric[i].meta.parent_kind == "PackageVersion" data.resources.Metric[i].meta.parent_uuid == data.resources.PackageVersion[_].uuid score := data.resources.Metric[i].spec.metric_values.scorecard.score_card.overall_score score < 7 result = { "Endor": { "PackageVersion": data.resources.Metric[i].meta.parent_uuid }, "Score": sprintf("%v", [score]) } } ``` 5. Enter the OPA **Query Statement** for the rule in the following format: `data..`. For the example, the query statement is `data.examples.match_package_version_score` in the above Rego rule. 6. Select the **Resource Kinds** required to evaluate the policy. For the example above the required resource kinds are `PackageVersion` and `Metric`. 7. In **Group by Fields**, if applicable, list which custom output fields to group the findings by in addition to the resource UUID. Use this optional field if you want to be able to raise multiple findings against the same finding target. For example, a repository version may have multiple exposed secrets and thus there are multiple findings of the same type for the same repository version. You do not need to add all (or any) custom fields here, just the ones you want to be used to group the matches by. 8. Choose a **Severity** for the generated finding. 9. Enter a short **Summary** of the finding. 10. Enter an **Explanation** for the finding. You can include additional information or explain why this finding is important. 11. Describe how to mitigate the finding in **Remediation**. 12. Enter the **Finding Name**. 13. Select one or more categories for the finding in **Finding Categories**. 14. See steps 6-10 above under [Create a finding policy from template](#create-a-finding-policy-from-template) The application verifies the Rego syntax and query statement before creating the policy. However, the logic cannot be fully validated without input data. See also [validate policy](#validate-policy). #### Available resource kinds Every policy must specify the resource kinds it needs to execute the Rego logic. Requested resource kind objects for the current scan are made available to the Rego code under `data.resources.`. The following resource kinds are available: * [Project](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#project) * [Repository](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#repository) * [RepositoryVersion](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#repositoryversion) * [PackageVersion](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#packageversion) * [DependencyMetadata](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#dependencymetadata) * [LinterResult](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#linterresult) * [Metric](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#metric) #### Finding targets Findings are raised against finding targets. Findings targets have one of three resource kinds: 1. **Repository** (for example, default branch protections) 2. **RepositoryVersion** (for example, CI/CD coverage, secrets) 3. **PackageVersion** (for example, vulnerabilities, scores, licenses) Individual finding target records are identified by their universally unique identifier (UUID). The finding target record is the parent of the finding record. The finding target resource kind is **PackageVersion** for findings in the root package as well as for findings in its dependencies. A dependency **PackageVersion** record may or not be in the same namespace as the root package. The relationships between the root package and its dependencies is captured by the corresponding **DependencyMetadata** records. All **DependencyMetadata** records are children of the root **PackageVersion** record in the same namespace as the root **PackageVersion**. #### Expected output format All finding policies must generate the finding payload as json data, listing the [finding target](#finding-targets) resource kind and UUID under "Endor" in the following format. ```bash theme={null} foo[result] { result = { "Endor": { : }, : } } ``` ##### Custom output fields Custom key-value pairs are optional. The value is treated as a single string and must be formatted accordingly. If a custom key is specified in the **Group by Fields** list then the value is appended to the finding name (the key is not included). Example: `SSL disabled for Webhook ID #444611302`, where `SSL disabled for Webhook` is the value of the **Finding Name** field and `ID #444611302` is the value of a custom key. Otherwise, both the key and the value are listed at the end of the finding summary on a new line for each pair. Example: `Score: 4.10`. #### Validate policy See the [endorctl validate policy](/developers-api/cli/commands/validate) command for details on how to validate a custom policy and inspect the matches returned for a given project. # License policies Source: https://docs.endorlabs.com/platform-administration/policies/finding-policies/license-policies/index Learn about the predefined finding policy templates for open source license risk management. ## Policy templates for open source license detection Endor Labs provides the following policy templates for detecting open source license usage. See [Finding Policies](/platform-administration/policies/finding-policies/license-policies/..) for details on how to create policies from policy templates. # RSPM policies Source: https://docs.endorlabs.com/platform-administration/policies/finding-policies/managing-scm-configuration/index Learn about the out-of-the-box finding policies for repository security posture management (RSPM). Strong information security practices are necessary to secure your open source code used in your development and delivery infrastructure. ## Policies for repository security posture management Endor Labs comes with the following out-of-the-box policies that help you determine the effectiveness of your security practices. See [Finding Policies](/platform-administration/policies/finding-policies/managing-scm-configuration/..) for details on how to **enable**, **disable**, or **edit** out-of-the-box policies. # Open-source policies Source: https://docs.endorlabs.com/platform-administration/policies/finding-policies/oss-policies/index Learn about the out-of-the-box finding policies for open source risk management. Open source risk policies generally fall into multiple categories: * Vulnerabilities - Known vulnerabilities associated with a software component. * Operational Risk - Issues that may make it more expensive to address any application impacting bug, including a security vulnerability. * License Risk - Issues that may cause legal or compliance risk associated with your software. ## Policies for open source risk management Endor Labs comes with the following out-of-the-box finding policies to detect open source risks. See [Finding Policies](/platform-administration/policies/finding-policies/oss-policies/..) for details on how to **enable** or **disable** out-of-the-box policies. # SAST policies Source: https://docs.endorlabs.com/platform-administration/policies/finding-policies/sast-policies/index Learn about the predefined finding policy templates for SAST used in your software development environment. Endor Labs provides the following finding policy templates for detecting SAST issues. See [Finding policies](/platform-administration/policies/finding-policies/) for details on how to create policies from policy templates. See [SAST severity matrix](/scan/sast/rule-based-sast#sast-severity-matrix) to understand how Endor Labs assigns severity to SAST findings. # Secret policies Source: https://docs.endorlabs.com/platform-administration/policies/finding-policies/secret-policies/index Learn about the out-of-the-box finding policies and templates for secret detection. ## Policies for secret detection Endor Labs comes with the following out-of-the-box finding policies to detect leaked secrets. See [Finding Policies](/platform-administration/policies/finding-policies/secret-policies/..) for details on how to **enable**, **disable**, or **edit** out-of-the-box policies. The out-of-the-box secret policies can be deleted and re-created from the corresponding policy templates. See [Policy templates for secret detection](#policy-templates-for-secret-detection) below. ## Policy templates for secret detection Endor Labs provides the following finding policy templates for detecting secrets. See [Finding Policies](/platform-administration/policies/finding-policies/secret-policies/..) for details on how to create policies from policy templates. # Policies Source: https://docs.endorlabs.com/platform-administration/policies/index Create and manage finding, action, exception, and remediation policies. Policies are rules that allow you to customize the behavior of the Endor Labs scan. You can use policies to: * Enable, disable, or edit out-of-the-box features * Create custom findings * Set guardrails for the development process * Create custom ticketing or messaging workflows Endor Labs includes multiple out-of-the-box policies that enable you to get started quickly. Policy templates help you create custom policies and configure workflows around issues like known vulnerabilities, license risks, code review guidelines, repository configurations, and outdated, unmaintained, or unused dependencies. See also [configure policy settings](/platform-administration/configure-system-settings#configure-policy-settings). You can also write policies from scratch using [Rego policy language](https://www.openpolicyagent.org/docs/latest/policy-language/) and customize policies based on organizational rules and needs. You can tag projects to apply policies to specific projects. See [Tagging projects](/platform-administration/policies/tagging-projects) for more information. ## Key benefits of policies Policies are essential to define risk tolerance, set automated rules for open source components, check your repository or organization configuration, and more. * **Identify and triage issues** - Policies give you a quick and automated way to identify and triage issues in your environment. This saves valuable development time and ensures developers consider security issues at the early stages of application development. * **Improve decision-making** - Automating enforcement simplifies decision-making in an organization and reduces complexity. Policies make assessing the OSS components simpler and allow developers to focus on violations critical to the organization. * **Establish governance** - Use policies to set up an organization’s governance methods such as enforcing Multi-Factor Authentication, setting up code review guidelines, guidelines on the use of the open source components, preventing misconfiguration of source code repositories, and more. ## Policy types You can set up the following types of policies in Endor Labs. * [**Finding policies**](/platform-administration/policies/finding-policies): Enable or disable out-of-the-box features and create custom finding policies to identify and raise findings for issues in your development environment. For example, you can create a finding policy to raise findings for missing, unknown, problematic, or incompatible licenses. * [**Exception policies**](/platform-administration/policies/exception-policies): Identify findings that should be exempt from action policies. For example, you can create an exception policy to automatically dismiss all findings found in the `serverless-dns` package. * [**Action policies**](/platform-administration/policies/action-policies): Define the system behavior and set up workflows when a finding with a given set of properties is raised. For example, you can create an action policy to create a Jira task when packages with outdated dependencies are included in your projects. * [**Remediation policies**](/platform-administration/policies/remediation-policies): Define the conditions to remediate findings when an upgrade is available. For example, you can apply remediation when a low risk upgrade is available. * [**Package Firewall policy**](/package-firewall/policy): Define conditions to control package installations for malware, minimum package age, restricted licenses, vulnerabilities, exceptions, and send Slack notifications when a package installation is blocked or warned. # Remediation policies Source: https://docs.endorlabs.com/platform-administration/policies/remediation-policies/index Learn about remediation policies and how to use them. Remediation policies define the conditions for applying remediation to a finding when an upgrade is available that fixes the finding. ## Manage remediation policies You can view, enable, clone, disable, edit, or delete your Endor Labs remediation policies. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Remediation Policies**. 3. Use the search bar to search for a policy or click **Create Remediation Policy**. 4. Enable or disable a policy using the toggle. 5. To delete a policy, click the vertical three dots and select **Delete Policy**. 6. To edit a policy, click on the vertical three dots and select **Edit Policy**. 7. To clone a policy, click on the vertical three dots and select **Clone Policy**. ## View policy details 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Remediation Policies** to view the list of remediation policies. 3. Select a policy you want to review and click **View Details**. You can see the policy’s description, scope, and metadata. You can review the severity, finding categories, explanatory details, remediation steps and the Rego rules that implement the policy logic. View remediation policy details ## Create a remediation policy from a template You can create a remediation policy in Endor Labs to address a finding when specific conditions are met. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Click on the **Remediation Policies** tab. 3. Click **Create Remediation Policy** to create a new remediation policy. 4. Select a policy template. Currently, you can choose **Recommended Version Upgrades for Vulnerabilities**. 5. Next, choose the template parameters. * **Upgrade Risk**: The acceptable level of risk that a breaking change might occur with the upgrade. * **Severity:** Match upgrades that would fix findings with a particular severity. * **Exclude Test:** Select **Yes** to exclude version upgrade recommendations for fixing findings in test dependencies. * **Dependency Reachability:**: Match upgrades that address findings with the following level of dependency reachability. * Reachable dependency * Unreachable dependency * Potentially reachable dependency * **Function Reachability:** Match upgrades that address findings with the following level of function reachability. * Reachable function * Unreachable function * Potentially reachable function * **Minimum Number of Findings:** Only match upgrades that resolve a minimum number of findings equal to or greater than this value. 6. Select a notification target to be associated with the remediation policy. See [Integrations](/integrations) for more information on creating notification integrations. 7. You can **Assign Scope** to the remediation policy by specifying what projects the policy has to scan. * In **Inclusions**, enter the projects and the tags of the projects that you want to scan. * In **Exclusions**, enter the projects and the tags of the projects that you do not want to scan. Exclusions take precedence over the inclusions, in case of a conflict. * Click the link to view the projects included in the remediation policy scan. * Click **Add project tag to these projects** and enter a tag for the selected projects. Click **Save Tags** to apply it or **Reset Tags** to discard changes. * You can set custom tags for your projects from **Projects** > **Settings** > **Custom Tags**. See [Tagging projects](/platform-administration/policies/tagging-projects) for more information about creating project tags. 8. Finally, you must **Name Your Remediation Policy**. * Enter a human-readable **Name** for your remediation policy. * Enter a **Description** for your remediation policy that explains its function. * Enter any **Policy Tags** that you want to associate with your policy. Tags can have a maximum of 255 characters and can contain letters, numbers, and characters = @ \_ -. 9. **Advanced**: When you define a policy, it applies to the current namespace and all its child namespaces. To prevent the policy from being applied to any child namespace, click **Advanced** and deselect **Propagate this policy to all child namespaces**. 10. Click **Create Remediation Policy**. The policy is enabled by default. Rescan the project to apply the newly created remediation policy and update the findings. # Tag projects Source: https://docs.endorlabs.com/platform-administration/policies/tagging-projects/index Learn about tagging projects to manage policies in Endor Labs All Endor Labs policies provide the option to define inclusion and exclusion criteria based on project tags. This allows you to implement exception workflows, to onboard new teams or business units, and to set specific policies that only apply to sets of projects, such as those that are mature or the crown jewel applications of an organization. Most organizations have projects with differing compliance and security requirements. Adopting a single standard for all projects can lead to challenges. While many controls apply equally across an environment, some controls are excessive or irrelevant for projects that don't need to meet specific regulatory frameworks, or do not process sensitive information. For example, an organization may want to look for leaked secrets in all repositories, but may not require a robust vulnerability management program and branch protection strategy on projects where internal documentation is developed. The following reference tagging strategies can help organizations align their policies with their internal control needs. ## Tag your projects Tags add additional metadata to projects and help you identify them. You can also use the project tags to define the scope of a finding or an action policy for a project. * For more details on finding policies, see [Finding policies](/platform-administration/policies/finding-policies) * For more details on action polices, see [Action policies](/platform-administration/policies/action-policies) To create tags for a project: 1. Select **Projects** from the left sidebar. 2. Select a project and click **Settings**. 3. Type a name for the tag in **Custom Tags** and press Enter. Tags can have a maximum length of 255 characters and can contain letters (A-Z), numbers (0-9), and characters (=@-\_). 4. Click **Save Tags**. 5. Use **Reset Tags** to make a new entry. # Configure proxy server settings Source: https://docs.endorlabs.com/platform-administration/proxy-server-configuration/index Configure proxy settings on machines that need to connect to Endor Labs when Internet access is limited to proxy-only connections. You must configure proxy settings on machines that need to connect to Endor Labs when Internet access is limited to proxy-only connections. These settings are required for running the endorctl client for scans, for self-hosted runners in CI/CD pipelines, and for using the Endor Labs REST API. ## Configure web proxy Set the following environment variables as system properties if you use Windows. ```shell theme={null} set HTTP_PROXY=http://username:password@: set HTTPS_PROXY=https://username:password@: ``` You can also set the variables as **User Variables** in **System > About > Advanced System Settings > Environment Variables**. You need to set the following environment variables as system properties if you use Linux or macOS. ```shell theme={null} export HTTP_PROXY=http://username:password@: export HTTPS_PROXY=https://username:password@: ``` ## Configure proxy for NTLM authentication If your proxy server uses NTLM authentication, set the following environment variables on machines that need to connect to Endor Labs when Internet access is limited to NTLM authenticated proxy-only connections. ```shell theme={null} export ENDOR_INSECURE_NTLM_USERNAME="your_username" export ENDOR_INSECURE_NTLM_PASSWORD="your_password" export ENDOR_INSECURE_NTLM_DOMAIN="your_domain" export ENDOR_INSECURE_NTLM_PROXY_URL="://:" ``` # Set up Entra ID for SSO using OIDC Source: https://docs.endorlabs.com/platform-administration/rbac/authentication-providers/custom-identity-providers/entraid-oidc-azure/index Learn how to setup Microsoft Entra ID as a custom external identity provider for SSO with Endor Labs. Integrate Endor Labs with Microsoft Entra ID (formerly Azure Active Directory) to use SSO through OpenID Connect (OIDC) protocol. Endor Labs honors the session duration set in OIDC, after which the user needs to reauthenticate. The token expiration claims (`exp`) control the session duration in OIDC. If your token does not include an expiration claim, the session duration defaults to four hours. The session duration cannot exceed four hours. If you set a session duration for more than four hours in the token expiration claim, the session duration defaults to four hours. Complete the following tasks to configure Microsoft Entra ID for SSO through OIDC: 1. [Create and configure an OIDC application in Azure](#create-and-configure-an-oidc-application-in-azure) 2. [Create Entra ID SSO in Endor Labs](#create-entra-id-sso-in-endor-labs) You must have administrator access to configure the application end-to-end in Azure. ## Create and configure an OIDC application in Azure Set up an application in Azure to enable OIDC configuration with Endor Labs. 1. Sign in to the [Azure portal](https://portal.azure.com/auth/login/). 2. Navigate to **App Registrations**. 3. Click **New Registration** to create a new application. 4. Enter `Endor Labs OIDC` as the name of your application. 5. Under **Supported Account Types**, select **Accounts in this organizational directory only (Single tenant)**. 6. Select **Web** as the platform under **Redirect URI**, then enter `https://api.endorlabs.com/v1/auth/oidc/callback` as the value. If you're using a EU tenant, use `https://api.eu.endorlabs.com/v1/auth/oidc/callback` as the value. 7. Click **Register**. 8. Once you've set up your application, navigate to **Authentication** in your application. 9. Enter `https://api.endorlabs.com/v1/auth/oidc/logout` in **Front-channel logout URL**. If you're using a EU tenant, use `https://api.eu.endorlabs.com/v1/auth/oidc/logout` as the value. 10. Click **Save**. ### Configure the Home page URL for MyApps SSO To launch Endor Labs from the Microsoft MyApps tile, configure the Home page URL in the Entra ID app registration. 1. In your application, navigate to **App registration** > **Branding & properties**. 2. Set the **Home page URL**, to `https://api.endorlabs.com/v1/auth/sso?tenant=your-tenant-namespace`. If you're using a EU tenant, use `https://api.eu.endorlabs.com/v1/auth/sso?tenant=your-tenant-namespace` as the Home page URL. This URL is used by Microsoft Entra ID when users launch Endor Labs from MyApps. Without it, the MyApps tile does not initiate an SSO session. ### Configure token claims in your application Once you’ve created your application, you need to configure token claims to identify and authorize users. 1. Navigate to **Manage** > **Token configuration** in your application. 2. Select **Add optional claim**. 3. Choose **ID** as the **Token type**. 4. Select **email** and **upn (User Principal Token)** from the claims. 5. Click **Add**. 6. To use groups, select **Add groups claim**. 7. Choose **Security groups** to limit the scope to groups assigned to the application. 8. Choose **Group ID** as the **Token type**. 9. Click **Save**. ### Create a client secret Create a client secret to allow Endor Labs to securely authenticate with the application. 1. Navigate to **Manage** > **Certificates & secrets** in your application. 2. Select **New client secret**. 3. Enter a description and select the expiry of the client secret. 4. Click **Add**. 5. Copy the **Value** immediately and store it in a secure location. ### Collect required values To configure the custom identity provider in Endor Labs, you must retrieve the **Application (client) ID** and **Directory (tenant) ID** from your Azure application. 1. Navigate to **App Registrations**. 2. Select your application. 3. Select **Overview** from the left sidebar. 4. Copy the **Application (client) ID** and **Directory (tenant) ID**. ## Create Entra ID SSO in Endor Labs Provide the Identity Provider details to configure Microsoft Entra ID in Endor Labs and allow users to seamlessly and securely sign in to Endor Labs. You must be an Endor Labs administrator to configure custom identity providers and authorization policies. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Custom Identity Provider**. 3. Select the **TYPE OF IDENTITY PROVIDER** as **OIDC**. 4. Enter the **IDENTITY PROVIDER NAME** as **Microsoft Entra ID**. 5. In the **DISCOVERY URL** enter your discovery URL. This typically consists of your Directory (tenant) ID followed by `/.well-known/openid-configuration`. For example, `https://login.microsoftonline.com/abcd1234-5678-90ef-ghij-1234567890kl/v2.0/.well-known/openid-configuration`. 6. Enter the client ID and client secret from Azure that you copied earlier. 7. Under **Advanced Configuration**, enter the following in **scopes**: **email**, **openid**, and **profile**. Press **enter** after every entry to add each attribute successfully. 8. If you are configuring group-based authentication ensure to add **groups** in **claim names**. 9. Click **Save Configuration**. Based on your Microsoft Entra ID configuration, you may need additional Azure claim names as scopes in Endor Labs. Consult your Microsoft administrator for additional guidance. ### Configure your Authorization Policy Once you've configured your custom identity provider in Endor Labs you must configure an authorization policy for your users and groups. To set up an authorization policy: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Auth Policy**. 3. Select **Add Auth Policy**. 4. Enter **Microsoft Entra ID** as your identity provider. 5. Select the permissions you'd like to assign your user or group. 6. Under claims update your **Key**. Use **email** to assign individual users through email or **groups** to assign a user by group. 7. Assign the value to the key as the email of the user or **group id** you would like to authorize. This value is case-sensitive. 8. Repeat as needed for any additional users or groups. # Set up Entra ID for SSO using SAML Source: https://docs.endorlabs.com/platform-administration/rbac/authentication-providers/custom-identity-providers/entraid-saml/index Set up Microsoft Entra ID as a custom identity provider for SSO with Endor Labs. You can integrate Endor Labs with Microsoft Entra ID (formerly Azure Active Directory) to use the Security Assertion Markup Language (SAML) 2.0 protocol for single sign-on (SSO) with Endor Labs. With the Endor Labs–Entra ID SAML integration, Endor Labs acts as the Service Provider (SP), and Microsoft Entra ID acts as the Identity Provider (IdP). When users sign in to Endor Labs using SAML, the SAML protocol triggers an authentication request to Entra ID, which returns a SAML assertion to Endor Labs. Users are then authenticated to access the application. The default session duration for SAML authentication is four hours. You can modify the `SessionNotOnOrAfter` attribute to lower the session duration. See [Session duration](/platform-administration/rbac/authentication-providers#session-duration) for more information. Complete the following tasks to set up SAML-based single sign-on (SSO) using Entra ID as the identity provider for Endor Labs. ## Create and configure SAML application in Entra ID To set up SAML, your organization's Entra ID administrator must create an application for Endor Labs and generate the SSO URL and certificate. To configure your Endor Labs application in Entra ID: 1. Sign in to Entra ID. Select **Enterprise Applications** and click **Create your own application**. 2. Enter `Endor Labs` as the name of your application and select **Integrate any other application you didn't find in the gallery (Non-gallery)**. 3. Click **Create** to initiate creating your enterprise application. 4. Under **Overview**, click **Single sign-on** and select **SAML**. This redirects you to the **SAML-based Sign-on** page. 5. Edit the following details in **Basic SAML Configuration** and click **Save**. * **Identifier (Entra ID)**: `https://api.endorlabs.com/v1/auth/sso` * **Reply URL (Assertion Consumer Service URL)**: `https://api.endorlabs.com/v1/auth/saml-callback?tenant=yourtenant` If you're using a EU tenant: * Identifier (Entra ID): `https://api.eu.endorlabs.com/v1/auth/sso` * Reply URL (Assertion Consumer Service URL): `https://api.eu.endorlabs.com/v1/auth/saml-callback?tenant=yourtenant` Replace `yourtenant` with your tenant name. Basic SAML configuration in Entra ID 6. In **Attributes & Claims**, select **Edit** to add required claims, additional claims and group claims. a. Select **Add new claim** and fill the following details: * **Name**: Enter `email`. * **Source**: Select **Attribute**. * **Source Attribute**: Select `user.email` from the list. b. Select **Add a group claim** and configure the following in the right sidebar. * **Which groups associated with the user should be returned in the claim?**: Select **Security groups**. * **Source attribute**: Select **Group ID** from the list. * **Advance options**: Select **Customize the name of the group claim**, and enter `groups` in **Name (required)**. Attributes and claims configuration in Entra ID c. Click **Save** and return to **SAML-based Sign-on**. 7. Copy the **App Federation Metadata URL** available in **SAML Certificates**. App Federation Metadata URL in SAML Certificates ## Create Entra ID SSO in Endor Labs After creating the application in Entra ID, configure Endor Labs to use Entra ID as the identity provider (IdP). To set up Entra ID as your SAML IdP: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Custom Identity Provider**. 3. Provide the following details. * **Type of Identity Provider**: SAML. * **Identity Provider Name**: Entra ID. * **SAML Identity Provider Metadata URL**: Enter the Metadata URL copied from SAML certificates section in Entra ID. * **Attributes**: Enter **email**, **groups**. Separate the attributes using the `enter` or `return` key. 4. Click **Save Configuration**. Custom Identity Provider configuration in Endor Labs ### Configure your authorization policy After setting up Entra ID as your SAML IdP, you must configure an authorization policy for your users and groups. To configure an authorization policy: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Auth Policy**. 3. Select **Add Auth Policy**. 4. Select **Entra ID SAML** from the **Identity Provider** list. 5. Choose the necessary permissions. See [authorization roles](/platform-administration/rbac/authorization-roles) for more information. 6. Configure **Claims** as a key-value pair. * For individual users, provide `user` as **Key** and the user's email as **Value**. * For groups, provide `groups` as **Key** and the group ID configured in Entra ID as **Value**. 7. Under **Advanced**, select a set of namespaces for which the authorization policy applies. # Set up SSO with Endor Labs Source: https://docs.endorlabs.com/platform-administration/rbac/authentication-providers/custom-identity-providers/index Set up SAML or OIDC single sign on for Endor Labs with in your organization. Single Sign-On (SSO) provides a seamless sign-in by enabling users to access external applications and services without re-entering the credentials. Endor Labs supports SAML or OIDC-based identity providers. SAML is an XML-based protocol used for exchanging authentication and authorization data between applications. OpenID Connect (OIDC) is an identity layer on top of the OAuth 2.0 framework that allows applications to verify the identity and claims of users. Using Endor Labs, you can integrate using an Identity Provider (IdP) that supports SAML or OIDC, such as Okta, Microsoft Active Directory Federation Services (AD FS), Azure Active Directory (AD), Google, or OneLogin. The default duration of a user session is four hours, if you have not set the session duration in your IdP. Endor Labs honors the session duration set in the IdP, after which the user needs to reauthenticate. You can set the session duration in the `SessionNotOnOrAfter` attribute for SAML. The token expiration claims (`exp`) control the session duration in OIDC. Session duration cannot be more than four hours. If you set a session duration for more than four hours at the IdP, the session duration defaults to four hours. Complete the following tasks to integrate an SSO-based identity provider with Endor Labs. ## Keep Service Provider (Endor Labs) details handy To configure Endor Labs as a SAML 2.0 app, you must have the following service provider details: * **Single sign-on URL**: This is the API endpoint of the application, where your identity provider redirects the user after successful authentication. You have to enter `https://api.endorlabs.com/v1/auth/saml-callback?tenant=yourtenant`. Replace `yourtenant` with your actual tenant name. If you're using a EU tenant, enter `https://api.eu.endorlabs.com/v1/auth/saml-callback?tenant=yourtenant` and replace `yourtenant` with your actual tenant name. * **Audience URI**: This is a globally unique name for the service provider. You have to enter `https://api.endorlabs.com/v1/auth/sso`. If you're using a EU tenant, enter `https://api.eu.endorlabs.com/v1/auth/sso`. To configure Endor Labs as an OIDC app, you must have the following service provider details: * **Sign-in redirect URIs**: This is the API endpoint of the application, where your identity provider redirects the user after successful authentication. You have to enter: `https://api.endorlabs.com/v1/auth/oidc/callback`. If you're using a EU tenant, enter `https://api.eu.endorlabs.com/v1/auth/oidc/callback`. * **Sign-out redirect URIs**: This is the API endpoint of the application, where your identity provider redirects the user after successful logout. You have to enter: `https://api.endorlabs.com/v1/auth/oidc/logout`. If you're using a EU tenant, enter `https://api.eu.endorlabs.com/v1/auth/oidc/logout`. ## Retrieve Setup information from your IdP The following information is needed for SAML and OIDC configuration setup in Endor Labs. ### Setup information for SAML Authentication To set up SAML SSO with Endor Labs you will need the following information from your IdP: * **Sign-On URL**: The SAML SSO remote sign-in URL of IdP. * **Issuer**: The unique ID of IdP for Endor Labs. * **Signing Certificate**: The public key certificate of your IdP. ### Setup Information for OIDC Authentication To set up OIDC SSO with Endor Labs you will need the following information from your IdP: * **Identity Provider Discovery URL**: The OIDC discovery URL of your identity provider. * **Client Key**: The unique key of IdP for Endor Labs. * **Client Secret**: The secret key of your IdP for Endor Labs. * **Required Claims and Scopes**: The required claims and scopes if non-standard for your OIDC connection. ## Configure SAML in Endor Labs Provide the Identity Provider SSO details in Endor Labs and allow users to seamlessly and securely sign in to Endor Labs. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Custom Identity Provider**. 3. Select the **TYPE OF IDENTITY PROVIDER** as **SAML**. 4. Enter a name for your **IDENTITY PROVIDER NAME**. 5. From **METADATA DEFINITION**, select **Metadata URL** and enter the **SAML Identity provider metadata URL** or **Discovery URL** from your IdP. 6. If you want to enter the identity provider details manually, choose **METADATA DEFINITION** as **Manual** and enter the following details that you saved from IdP. * DISCOVERY URL: Enter **Sign-On URL** from IdP. * ISSUER: Enter **Issuer** from IdP. * ATTRIBUTES: Enter your attributes such as email and groups. Type the values and press enter. * CERTIFICATE: Enter the **Signing Certificate** from IdP. 7. Click **Save Configuration**. ## Configure OIDC in Endor Labs Provide the following Identity Provider SSO details to configure OIDC SSO in Endor Labs and allow users to seamlessly and securely sign in to Endor Labs. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Custom Identity Provider**. 3. Select the **TYPE OF IDENTITY PROVIDER** as **OIDC**. 4. Enter the **IDENTITY PROVIDER NAME** for your selected identity provider. 5. Under **DISCOVERY URL** enter your discovery URL. In most cases, this is your Okta domain followed by /.well-known/ openid-configuration. For example, `https://endorlabs.okta.com/.well-known/openid-configuration`. 6. Enter your Client ID and Client Secret from your IdP. 7. Under **Advanced Configuration** enter the following scopes in the **scopes** section: **email**, **groups**, **profile**. Make sure to hit enter after each to add each attribute. 8. If you are configuring group-based authentication ensure to add **groups** in the **Claim Names** section. 9. Click **Save Configuration**. Based on your IdP configuration you may need additional claim names or scopes. Consult your IdP administrator for additional guidance. ## Configure your Authorization Policy Once you've configured your custom identity provider in Endor Labs you must set up an authorization policy for your users and groups. To configure an authorization policy: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Auth Policy**. 3. Click **Add Auth Policy**. 4. Enter the name you selected for your custom identity provider as your identity provider. 5. Select the permissions you'd like to assign your user or group. 6. Under claims update your **Key**. Use **email** to assign individual users through email or **groups** to assign a user by group. 7. Assign the value to the key as the email of the user or group you would like to authorize. This value is case-sensitive. 8. Repeat as needed for any additional users or groups. ## Verify Sign-in Use the user account to sign in to Endor Labs from your IdP and validate the SSO integration. 1. Sign in to IdP as a user. 2. Navigate to [https://app.endorlabs.com](https://app.endorlabs.com) If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. 3. Click Login with Enterprise SSO 4. Enter the namespace you'd like to sign in to within Endor Labs. For Okta-specific instructions, see [SSO using Okta](/platform-administration/rbac/authentication-providers/custom-identity-providers/okta-oidc) # Set up Okta for SSO using OIDC Source: https://docs.endorlabs.com/platform-administration/rbac/authentication-providers/custom-identity-providers/okta-oidc/index Learn how to setup Okta as a custom external identity provider for SSO with Endor Labs Endor Labs integrates with Okta to use SSO through OpenID Connect (OIDC) protocol. Endor Labs honors the session duration set in OIDC, after which the user needs to reauthenticate. The token expiration claims (`exp`) control the session duration in OIDC. If you do not have token expiration claims, the default session duration is four hours. Session duration cannot be more than four hours. If you set a session duration for more than four hours in the token expiration claim, the session duration defaults to four hours. Complete the following tasks to configure Okta for SSO through OIDC. ## Create and configure an OIDC application in Okta In Okta, configure the Endor Labs application as an OIDC application and generate a single sign-on URL and certificate. You must be an Okta administrator to configure the application end-to-end in Okta. 1. Sign in to the Okta admin account. 2. Navigate to **Applications** > **Applications**. 3. To create an app integration, click **Create App Integration**. 4. Select **OIDC - OpenID Connect**. 5. Under Application type select **Web Application** and click **Next**. 6. Enter the following details in **General Settings** and click **Next**. * **App integration name**: Enter Endor Labs. * **App Logo (optional)**: Upload the Endor Labs logo in PNG, JPG, or GIF format. The logo size must be less than 1 MB. * **Sign-in redirect URIs**: Enter `https://api.endorlabs.com/v1/auth/oidc/callback` * **Sign-out redirect URIs**: Enter `https://api.endorlabs.com/v1/auth/oidc/logout` If you're using a EU tenant: * Sign-in redirect URIs: `https://api.eu.endorlabs.com/v1/auth/oidc/callback` * Sign-out redirect URIs: `https://api.eu.endorlabs.com/v1/auth/oidc/logout` * Under **Assignments**: Select if you'd like to assign all users or only a specified group then click **Save**. 7. Once you've set up your application, some additional configuration is required. Navigate to **Sign On** in the application. 8. Under **OpenID Connect ID Token** select **Edit**. 9. Select **Groups claim type** as **Filter** and ensure **groups** is selected with the **Matches Regex** filter of `.*` or a regex matching your group or groups name. 10. Click **Save Configuration**. ### Assign the appropriate users and groups to the application Once you've created your Application you need to assign the appropriate users and groups as assignments. 1. Select **Assignments** in your newly created application. 2. Click **Assign** and select **Assign to people** or **Assign to groups** if you are configuring group authorization. 3. Search for and select the group you'd like to assign and click **Done**. ### Get Identity Provider details from Okta Once you've created your Okta app and assigned groups you must retrieve your Okta the Okta identity provider SSO details to configure Okta in Endor Labs. 1. Select **Sign On**. 2. From **Metadata Details**, copy the **Metadata URL**. 3. Save the following details and have them handy if you'd like to manually configure SAML: * **Sign-On URL**: The SAML SSO URL of Okta. * **Issuer**: The unique ID of Okta for Endor Labs. * **Signing Certificate**: The public key certificate of Okta. ## Configure Okta OIDC SSO in Endor Labs Provide the Identity Provider SSO details to configure Okta SSO in Endor Labs and allow users to seamlessly and securely sign in to Endor Labs. You must be an Endor Labs administrator to configure custom identity providers and authorization policies. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Custom Identity Provider**. 3. Select the **TYPE OF IDENTITY PROVIDER** as **OIDC**. 4. Enter the **IDENTITY PROVIDER NAME** as **Okta OIDC**. 5. Under **DISCOVERY URL** enter your discovery URL. In most cases, this is your Okta domain followed by `/.well-known/openid-configuration`. For example, `https://endorlabs.okta.com/.well-known/openid-configuration`. 6. Enter your Client ID and Client Secret from Okta. 7. Under **Advanced Configuration** enter the following scopes in the **scopes** section: **email**, **groups**, **profile**. Press **enter** after every entry to add each attribute successfully. 8. If you are configuring group-based authentication ensure to add **groups** in the **Claim Names** section. 9. Click **Save Configuration**. Based on your Okta configuration you may need additional claim names or scopes. Consult your Okta administrator for additional guidance. ### Configure your Authorization Policy Once you've configured your custom identity provider in Endor Labs you must configure an authorization policy for your users and groups. To set up an authorization policy: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Auth Policy**. 3. Select **Add Auth Policy**. 4. Enter **Okta OIDC** as your identity provider. 5. Select the permissions you'd like to assign your user or group. 6. Under claims update your **Key**. Use **email** to assign individual users through email or **groups** to assign a user by group. 7. Assign the value to the key as the email of the user or group you would like to authorize. This value is case-sensitive. 8. Repeat as needed for any additional users or groups. # Set up Okta for SSO using SAML Source: https://docs.endorlabs.com/platform-administration/rbac/authentication-providers/custom-identity-providers/okta-saml/index Learn how to setup Okta as a custom external identity provider for SSO with Endor Labs Endor Labs integrates with Okta to use SSO through either Security Assertion Markup Language (SAML) protocol. With the Endor Labs-Okta SAML integration, Endor Labs acts as the Service Provider (SP), and Okta acts as the Identity Provider (IdP). When users sign in to Endor Labs using the SAML authentication method, the IdP (Okta) sends a SAML assertion to the browser that is passed to the SP (Endor Labs). This enables Okta to establish a secure connection with the browser and then authenticate the users to sign in to Endor Labs. Endor Labs honors the session duration set in SAML, after which the user needs to reauthenticate. You can set the session duration in the `SessionNotOnOrAfter` attribute for SAML. If you do not set the attribute, the default session duration is four hours. Session duration cannot be more than four hours. If you set the `SessionNotOnOrAfter` attribute for more than four hours, the session duration defaults to four hours. The following high level steps allow you to successfully configure Okta for SSO through SAML: ## Create and configure a SAML application in Okta In Okta, configure the Endor Labs application as a SAML 2.0 application and generate a single sign-on URL and certificate. You must be an Okta administrator to configure the application end-to-end in Okta. 1. Sign in to the Okta admin account. 2. Go to **Applications** > **Applications**. 3. To create an app integration, click **Create App Integration**. 4. Select **SAML 2.0** and click **Next**. 5. Enter the following details in **General Settings** and click **Next**. * **App Name**: Enter Endor Labs. * **App Logo (optional)**: Upload the Endor Labs logo in PNG, JPG, or GIF format. The logo size must be less than 1 MB. * **App Visibility (optional)**: Select this option to hide the Endor Labs icon from users in the Okta dashboard. 6. Enter the following in SAML Settings. * **Single sign-on URL**: Enter `https://api.endorlabs.com/v1/auth/saml-callback?tenant=yourtenant`. Replace `yourtenant` at the end with your actual tenant name. If you're using a EU tenant, enter `https://api.eu.endorlabs.com/v1/auth/saml-callback?tenant=yourtenant` and replace `yourtenant` with your actual tenant name. * **Audience URI**: Enter `https://api.endorlabs.com/v1/auth/sso` If you're using a EU tenant, enter `https://api.eu.endorlabs.com/v1/auth/sso`. * **Relay State**: Leave this field empty * **Name ID format**: Select **Unspecified**. * **Application username**: Select **Email**. * **Update application username on**: Ensure **Create/Update** is selected. 7. Click **Show Advanced Settings** and ensure the following default details are set: * **Response**: Select **Signed**. * **Assertion Signature**: Select **Signed**. * **Signature Algorithm**: Select **RSA-SHA256**. * **Digest Algorithm**: Select **SHA256**. * **Assertion Encryption**: Select **Unencrypted**. 8. Configure your attribute statements: Attribute statements are specific properties associated with individual users and are used for including user provisioning, access control, or user profile management. To configure each individual user in Endor Labs you can use **Attribute Statements**. To configure users using Okta groups, such as groups integrated with Active Directory accounts use **Group Attribute Statements**. 1. Enter the following details in **Attribute Statements** for individual authorization: * **Name**: Enter **email**. * **Name format**: Select **Basic**. * **Values**: Select **user.email**. 2. Enter the following details in **Group Attribute Statements** for group authorization: * **Name**: Enter **groups**. * **Name format**: Select **Basic**. * **Filter**: As best practice, filter the groups being sent by choosing one of the following options. * Select **Matches regex** and enter a regular expression to specify groups. * Select **Starts With** to filter groups based on a prefix, sending only groups that begin with the specified string. 9. Click **Next**. 10. Select **I'm a Okta customer adding an internal app**, and click **Finish**. ### Assign the appropriate users and groups to the application Once you've created your Application you need to assign the appropriate users and groups as assignments. 1. Select **Assignments** in your newly created application. 2. Click **Assign** and select **Assign to people** or **Assign to groups** if you are configuring group authorization. 3. Search for and select the group you'd like to assign and click **Done**. ### Get Identity Provider details from Okta Once you've created your Okta app and assigned groups, then collect the identity provider SSO details to configure Okta in Endor Labs. 1. Select **Sign On**. 2. From **Metadata Details**, copy the **Metadata URL**. 3. Save the following details and have them handy if you'd like to manually configure SAML: * **Sign-On URL**: The SAML SSO URL of Okta. * **Issuer**: The unique ID of Okta for Endor Labs. * **Signing Certificate**: The public key certificate of Okta. ## Configure Okta SSO in Endor Labs Provide the Identity Provider SSO details to configure Okta SSO in Endor Labs and allow users to seamlessly and securely sign in to Endor Labs. You must be an Endor Labs administrator to configure custom identity providers and authorization policies. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Custom Identity Provider**. 3. Select the **TYPE OF IDENTITY PROVIDER** as **SAML**. 4. Enter the **IDENTITY PROVIDER NAME** as **Okta SAML**. 5. From **METADATA DEFINITION**, select **Metadata URL** and enter the **Metadata URL** that you downloaded from Okta. 6. If you want to manually enter the identity provider details, choose **METADATA DEFINITION** as **Manual** and enter the following details, you saved from Okta. See [Get Identity Provider details from Okta](#get-identity-provider-details-from-okta) * **DISCOVERY URL**: Enter **Sign-On URL** from Okta. * **ISSUER**: Enter **Issuer** from Okta. * **ATTRIBUTES**: Enter your attributes such as email, groups, or more. Type the values and press enter. * **CERTIFICATE**: Enter the **Signing Certificate** from Okta. 7. Under **Attributes** enter **email** and **groups**, Press **enter** after each entry to add each attribute. 8. Click **Save Configuration**. You must be an Endor Labs administrator to configure custom identity providers and authorization policies. ### Configure your Authorization Policy Once you've configured your custom identity provider in Endor Labs you must configure an authorization policy for your users and groups. To set up an authorization policy: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Auth Policy**. 3. Select **Add Auth Policy**. 4. Enter **Okta SAML** as your identity provider. 5. Select the permissions you'd like to assign your user or group. 6. Under claims update your **Key**. Use **email** to assign individual users through email or **groups** to assign a user by group. 7. Assign the value to the key as the email of the user or group you would like to authorize. This value is case-sensitive. 8. Repeat as needed for any additional users or groups. # Authentication providers Source: https://docs.endorlabs.com/platform-administration/rbac/authentication-providers/index Learn about authentication providers and their session token durations in Endor Labs. Authentication through Endor Labs is done through an external identity provider. Some authentication mechanisms are generally designed for human users, while others are designed for machine identities. Endor Labs supports the following authentication mechanisms for human users. * **Google** - Authentication is provided through a user's Google Workspace account. * **GitHub** - Authentication is provided through a user's GitHub account. * **GitLab** - Authentication is provided through a user's GitLab account. * **Email** - Authentication is provided through an email link sent to a user. * **Custom Identity Providers** - An enterprise identity provider such as Okta or VMware One, which uses SAML or OIDC protocol. See [Custom identity providers](/platform-administration/rbac/authentication-providers/custom-identity-providers) for more information. The following authentication mechanisms designed for machine identities, such as continuous integration or automation systems, are supported. * **Google Cloud** - With Google Cloud workload identity federation service accounts may be used to federate identity to Endor Labs. See [Keyless authentication](/setup-deployment/ci-cd/keyless-authentication/google-keyless-auth) for more information. * **GitHub Action OIDC** - With [GitHub Action OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers) you can federate the identity of your workloads to Endor Labs. See [Keyless authentication](/setup-deployment/ci-cd/keyless-authentication/github-keyless-auth) for more information. * **AWS Role** - With AWS identity federation your can use the [AWS ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) of the role acts as the identity of a machine user. See [Keyless authentication](/setup-deployment/ci-cd/keyless-authentication/aws-keyless-auth) for more information. ## Session duration The duration of the session token determines how long a user stays authorized in Endor Labs. At the end of the session duration, the user authentication is invalidated and requires reauthentication. The following table provides the session duration for each supported authentication provider. The default session token duration for Custom Identity Providers (IdPs) is 4 hours, provided no specific session duration is configured in your IdP. Endor Labs respects the session duration defined in your IdP, after which users must reauthenticate. For SAML-based integrations, you can set the session duration using the `SessionNotOnOrAfter` attribute. In OIDC, the token expiration claims (`exp`) control the session duration. The maximum allowed session duration is 4 hours. If your IdP is configured with a session duration exceeding 4 hours, the session will automatically default to a 4-hour limit. # Authorization policies Source: https://docs.endorlabs.com/platform-administration/rbac/authorization-policies/index Learn how to manage authorization policies in Endor Labs. Authorization policies define the permissions provided to an identity authenticated by a supported identity provider when that identity meets specific rule criteria defined as attributes or claims about the identity. Authorization policies must contain the following information: * The [supported identity provider](/platform-administration/rbac/authentication-providers) through which a given identity comes from. * The [role](/platform-administration/rbac/authorization-roles) provided to an identity. * An optional expiration time for the policy. * The rule criteria or claims required for an identity to access Endor Labs. After setting up the authorization policy, you can [invite users to Endor Labs](/platform-administration/rbac/invitations). ## Set up authorization policies To set up an authorization policy to your Endor Labs tenant: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Auth Policy**. 3. Select **Add Auth Policy**. 4. Select the identity provider for which you want to configure an authorization policy. 5. Select the role to be granted to a matching identity. 6. Select an expiration time for the authorization rule. This may be either **No expiration**, **24 hours**, **72 hours**, **one week**, **two weeks**, **30 days**, **60 days**, or **90 days**. 7. Select the [claims](#claims) for which the authorization rule will provide access. 8. Select [**Add Permission Rule**](#permission-rules) to define granular permissions by specifying resource kinds and allowed methods. 9. Under **Advanced**, select a set of namespaces for which the authorization policy applies. If you choose to propagate this policy to all child namespaces, then the authorization policy will apply to any selected namespaces and their children. 10. Click **Add Auth Policy** to save your authorization policy. After adding the authorization policy, a user with the corresponding authorization claims can sign in to Endor Labs with their configured permissions. See [Invite users to Endor Labs](/platform-administration/rbac/invitations). ## Claims Claims are key-value pairs from your identity provider's JWT or SAML token that Endor Labs evaluates when a user authenticates. Each claim has a: * **Key**: The token attribute name. * **Value**: The expected attribute value. When an incoming token's attributes match all the claims in a policy, Endor Labs grants the policy's assigned role to that user. When a policy contains multiple claims, all of them must match for the policy to apply. Claim values are case-sensitive. The following are the claim keys available for each identity provider and what values to enter. Use the `user` key with the user's platform username as the value. The username is the handle the user signs in with on GitHub or GitLab, not their display name or email address. For example, to grant access to a GitHub user with the handle `jsmith`, set **Key** to `user` and **Value** to `jsmith`. Use the `user` key to grant access to a specific Gmail address, or the `domain` key to grant access to all users in an email domain. For example: * To grant access to a single user, set **Key** to `user` and **Value** to `jsmith@example.com`. * To grant access to everyone in a domain, set **Key** to `domain` and **Value** to `example.com`. Using `domain` is useful for organizations where all employees share a corporate Google Workspace domain and you want to grant access to the whole group rather than individual users. Use the `email` key with the principal email address of your workload's service account. This is typically a service account address in the format `name@project-id.iam.gserviceaccount.com`. Use the `user` key to restrict access to workflows running in a specific GitHub organization or repository. Set the value to the organization or repository in the format `org` or `org/repo`. For example: * To allow any workflow in the `acme` organization, set **Value** to `acme`. * To restrict access to a specific repository, set **Value** to `acme/payments-service`. This is commonly used to authenticate CI/CD pipelines to Endor Labs without storing credentials. Use the `user` key with the full AWS ARN of the IAM role your machine uses to authenticate. For example, `arn:aws:iam::123456789012:role/endorlabs-scanner`. The ARN must match exactly as it appears in your AWS IAM configuration. Use the `email` key with the email address to which Endor Labs sends the authentication link. This is for users who sign in via a one-time link sent to their email address. Azure authorization policies require three claim keys that together uniquely identify the application identity: * `tid`: The Directory (tenant) ID of your Azure Active Directory tenant. * `appid`: The Application (client) ID of the registered application in Azure. * `oid`: The Object ID assigned to the application or managed identity in the tenant. The following keys are optional and can be used to further narrow access: * `az_jwt_sub`: The subject claim from the Azure JWT token. Use this to scope the policy to a specific identity within the application. * `subscriptions`: The Azure subscription ID, to restrict access to workloads running under a specific subscription. Use any key-value pair that your SAML or OIDC identity provider includes in its token. The key must match the claim attribute name exactly as it appears in the token. For example, if your Okta OIDC token includes a `groups` claim, set **Key** to `groups` and **Value** to the group name you want to match. If your organization maps department information into a custom claim called `department`, you can use that to scope access to a specific team. ## Permission rules Permission rules control what actions an authenticated identity can perform in Endor Labs. Each rule has two parts: * **Resource kind**: The type of object the rule applies to, such as `Project`, `Finding`, `AuthorizationPolicy`, or `ScanProfile`. Use `*` to apply the rule to all resource kinds. * **Methods**: The operations allowed on that resource. The following methods are available: * **Read**: Use this to grant view-only access to a resource without allowing any modifications. * **Create**: Use this to allow an identity to add new resources, such as creating projects or scan profiles. * **Update**: Use this when an identity needs to edit resources it did not necessarily create, such as updating findings or policies. * **Delete**: Assign this only when the identity explicitly needs to delete resources, as it cannot be undone. * **All**: Use this when an identity needs full control over a resource type. You can add multiple rules to a single policy to compose exactly the access level you need. For example, you could allow `Read` on all resources using `*`, then add a separate rule granting `Create` and `Update` on `Project` only, giving a CI service account the ability to run scans without broader write access. Permission rules in an authorization policy ## Search authorization policies You can use the search functionality to find authorization policies based on specific criteria. To search for authorization policies: 1. Select **User menu** > **Settings** > **Access Control**. 2. Select **Auth Policy**. 3. Use the search bar to find policies by: * **Rule**: Search policies by any text or string patterns within the rule definitions. * **Created By**: Search policies by the email address of the creator. * **Namespaces**: Search policies associated with a specific namespace. Auth Policy search ### Edit authorization policies To edit an authorization policy: 1. Select **User menu** > **Settings** > **Access Control**. 2. Select **Auth Policy**. 3. Click the vertical three dots on the right side of the policy you want to edit and click **Edit Auth Policy**. 4. You can update the identity provider, permission, expiration time, claims of key and value, and namespaces the policy applies to. 5. Click **Propagate this policy to all child namespaces** to apply this policy to all child namespaces within the hierarchy. 6. Click **Update Auth Policy**. Edit Auth Policy ### Delete authorization policies To delete an authorization policy: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Auth Policy**. 3. Click the vertical three dots on the right side of the policy you want to delete and click **Delete Auth Policy**. 4. Click **Confirm** in **Delete Authorization Policy**. ### Grant support access You can give the Endor Labs team read-only access to your namespaces for a limited time, allowing them to offer technical support and resolve issues. You can revoke access and delete these policies at any time. See [delete authorization policy](#delete-authorization-policies) for more information. To grant support access to your namespace: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Auth Policy**. 3. Select **Grant Support Access**. 4. Select an expiration time for the access from the drop down menu. 5. Click **Grant Access**. # Authorization roles Source: https://docs.endorlabs.com/platform-administration/rbac/authorization-roles/index Learn how to set permissions using authorization roles. Authorization roles define the permissions on accessing and using Endor Labs and its features. Each authorization role has a set of associated permissions that determine the extent of access to Endor Labs. Ensure that you assign the right role for the right situation and follow the principle of least privilege (PoLP). You need to assign an authorization role when you create [authorization policies](/platform-administration/rbac/authorization-policies) and [API keys](/platform-administration/api-keys#create-an-api-key). The following roles are available: # Manage access to Endor Labs Source: https://docs.endorlabs.com/platform-administration/rbac/index Learn how to manage access user and machine access to Endor Labs. Endor Labs comes with a built-in attribute based access control system. Attribute-based access control (ABAC) is an authorization model that evaluates attributes (or the characteristics of an identity), rather than roles, to determine access. See [Authorization policies](/platform-administration/rbac/authorization-policies) for more information on managing authorization policies. Endor Labs uses external identity providers to authenticate all users and the attributes associated with the identity to authorize them. The following sections provide information on authentication providers and how you can configure them. * [Authentication providers](/platform-administration/rbac/authentication-providers) * [Custom identity providers](/platform-administration/rbac/authentication-providers/custom-identity-providers) After you configure authentication and authorization policies, you can invite users. See [Invitations](/platform-administration/rbac/invitations) for more information. # Manage user invitations Source: https://docs.endorlabs.com/platform-administration/rbac/invitations/index Invite your team to work with you on Endor Labs. Endor Labs provides attribute based access control to manage users across tenants. Provision User access to Endor Labs through one of the following methods: 1. **Send user invitations** - Specifically invite a user through email to sign in using their own selected identity provider. 2. **Configure authorization policies** - Define specific identities or attributes for a given identity to provide necessary access to Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies) for more information. ## Invite users to Endor Labs Invite specific users to access your Endor Labs tenant using their preferred external identity provider. When a user is sent an invitation to your tenant, they receive an invitation to sign in to Endor Labs with the identity provider of their choice. When a user accepts an invitation an authorization policy is created for them using their selected identity provider. To invite a new user to Endor Labs: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Invitations**. 3. Click **Invite your team**. 4. Enter the email address of the user that you would like to collaborate with. If you would like to invite multiple users enter their email addresses as a comma separated list. 5. Click **Invite Users**. An email will be sent to the email address inviting the user to your tenant namespace. The email will provide a link for them to access your tenant namespace, and they can start collaborating on your projects. If the users you invite are using GitHub or GitLab as their external identity provider, the email address of the user you would like to invite must be the primary email address of the account. ## Invalidate a user invitation To delete a user invitation: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Invitations**. 3. Choose an invitation that you would like to delete and click **Delete**. # April 2026 Source: https://docs.endorlabs.com/releasenotes/april-2026/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Bazel Bzlmod support for JavaScript projects New Endor Labs now supports Bzlmod when you use Bazel aspects for JavaScript projects. Bzlmod support requires Bazel aspects with `rules_js` >= 2.0.0. For more information, see [Bazel](/scan/bazel) and [Bazel Aspects](/scan/bazel/bazel-aspects). ### Bazel Bzlmod support for Rust projects New Endor Labs now supports Bzlmod when you use Bazel aspects for Rust projects. Bzlmod support requires Bazel aspects with `rules_rust` >= 0.40.0. For more information, see [Bazel](/scan/bazel) and [Bazel Aspects](/scan/bazel/bazel-aspects). ### Detect imposter commits in GitHub Actions workflows New Endor Labs now supports verifying that a commit SHA pinned in a workflow exists in the action’s upstream GitHub repository. A critical finding is raised when the commit cannot be found, as this may indicate an imposter commit or a supply chain attack. For more information, see [GitHub Action policies](/platform-administration/policies/finding-policies/github-action-policies#policies-for-assessing-configuration-settings-in-workflow-files). ### Bazel Bzlmod support for Swift projects New Endor Labs now supports Bzlmod when you use Bazel aspects for Swift projects. Bzlmod support requires Bazel aspects with `rules_swift` >= 2.0.0. For more information, see [Bazel](/scan/bazel) and [Bazel Aspects](/scan/bazel/bazel-aspects). ### Bazel Bzlmod support for Python projects New Endor Labs now supports Bzlmod when you use Bazel aspects for Python projects. Bzlmod support requires Bazel aspects with `rules_python` >= 0.30.0. For more information, see [Bazel](/scan/bazel) and [Bazel Aspects](/scan/bazel/bazel-aspects). ### Automatic requirements file detection in Python Enhancement Endor Labs now supports auto detection of non-standard pip requirement `.txt` files. Endor Labs identifies files that match pip requirement patterns and treat them as manifests, which reduces the need to maintain long lists of custom requirement files. For more information, see [Python](/scan/sca/python#handling-custom-and-multiple-requirement-files-in-pip). ### Automatically scan new repositories Enhancement Endor Labs scans new repositories in your organization as soon as they are created when the GitHub App (Pro) or the GitHub Enterprise Server App is installed with **All repositories** selected. This enables pull request scanning immediately, without waiting for the next scheduled scan. For installation scope, monitoring scans, and pull request checks, see [Deploy Endor Labs GitHub App (Pro)](/setup-deployment/scm-integrations/github-app) and [Deploy Endor Labs GitHub Enterprise Server App](/setup-deployment/scm-integrations/github-app/github-enterprise-app). ### Longer finding tags Enhancement Endor Labs now supports finding tag lengths of up to 255 characters. This helps prevent scan errors when findings include longer tag values, such as container image names or Bazel targets. For more information, see [Tagging projects](/platform-administration/policies/tagging-projects#tag-your-projects). # August 2026 Source: https://docs.endorlabs.com/releasenotes/august-2026/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Agents Hub New The Agents Hub helps you discover the security agents Endor Labs publishes and to see how your team uses them. Filter the catalog by category or search it by name, then open an agent to read what it does and copy the install command for your AI coding assistant. You can also view run history of the agents and see how your team uses them. For more information, see [Agents Hub](/secure-ai-coding/agents-hub). ### Allow safe versions in Package Firewall New You can now configure Package Firewall to install a safe version automatically instead of blocking the request, when a package is flagged for malware or doesn't meet the minimum package age. Select **Allow safe versions only (curate)** for these conditions so the package manager resolves and installs a safe version instead of failing — developers get a working install without seeing a block. This action is available for the npm and PyPI ecosystems. For more information, see [Allow safe versions](/package-firewall/policy#allow-safe-versions). ### Block Azure DevOps merges on PR scan findings Enhancement You can now block pull requests from merging in Azure DevOps when a PR scan detects findings that match an action policy. Configure an action policy that breaks the build to choose which findings gate a merge, and an Azure DevOps branch policy that requires the Endor Labs status check. This ensures that the findings your action policy targets are resolved before code reaches your default branch. For more information, see [Block pull requests on findings](/scan/pr-scans#block-pull-requests-on-findings). ### OpenCode support for the MCP server Enhancement The Endor Labs MCP server now supports OpenCode, so you can scan dependencies, detect vulnerabilities, find leaked secrets, and review code for security issues directly inside OpenCode. For more information, see [Endor Labs MCP server in OpenCode](/setup-deployment/mcp/opencode). # July 2026 Source: https://docs.endorlabs.com/releasenotes/july-2026/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Kotlin support for Bazel projects New Endor Labs now supports software composition analysis and reachability analysis for Kotlin in Bazel projects. Endor Labs analyzes `kt_jvm_library`, `kt_jvm_binary`, and `kt_jvm_test` targets built with `rules_kotlin` and resolves their dependencies as Maven packages. For more information, see [Bazel](/scan/bazel). ### EU data residency New Endor Labs now offers a dedicated EU-hosted environment for customers who require EU data residency. When you onboard as an EU tenant, all your data is stored and processed on Azure infrastructure in the EU region. EU tenants use distinct endpoints: `https://app.eu.endorlabs.com` for the Endor Labs application and `https://api.eu.endorlabs.com` for API and CLI access. API keys are region-bound and must be created from within your EU tenant. ### Hugging Face organization model inventory New Endor Labs can now scan all models in a Hugging Face organization, and score them for security, activity, popularity, and quality. Connect your organization using a Hugging Face access token to scan public and private models and score them. For more information, see [Hugging Face organization models](/secure-ai-coding/huggingface-organization). ### Finding Refresh scan type in scan history New Endor Labs now surfaces **finding-refresh** scans in scan history. A finding-refresh scan is a system-triggered, lean scan that recomputes vulnerability findings using stored dependency metadata after new security intelligence is ingested, so findings are updated without waiting for the next scheduled scan cycle. You can identify these scans by their **Finding Refresh** label in the **Type** column and filter for them using the **Scan Type** dropdown. For more information, see [Scan history](/inventory-insights/scan-history). ### Google Artifact Registry support for Package Firewall New You can now route package installations for npm, PyPI, and Maven through the Package Firewall using Google Artifact Registry. Configure a remote repository with the Package Firewall as its custom upstream, and every request is checked against the Endor Labs malware database and your policies to block, warn, or allow the package installation. For more information, see [Configure the Package Firewall with Google Artifact Registry](/package-firewall/google-artifact-registry). ### User attribution for Package Firewall New Each package installation request routed through the Package Firewall can now be attributed to the developer and machine that initiated it. User attribution tags every request with the requester's identity in the format `@`. Configure user attribution through the MDM deployment scripts and view the attributed identity in the Package Firewall logs. For more information, see [User attribution](/package-firewall/mdm-deployment#user-attribution). ### Slack notifications for Package Firewall New You can now receive a Slack message when the Package Firewall blocks or warns on a package installation, so you know about risky installations in real time. Set up the policy to configure notifications when a package installation matches specific reasons such as malware, minimum package age, restricted licenses, or vulnerabilities. For more information, see [Set up notifications](/package-firewall/policy#set-up-notifications). ### Azure DevOps App PR scans Beta New The Endor Labs Azure DevOps App now supports automated pull request scanning for security vulnerabilities, policy violations, and exposed secrets. You can also configure PR comments directly on your pull requests when issues are detected, helping developers address security concerns before merging code. For more information, see [Azure DevOps App PR scans](/setup-deployment/scm-integrations/azure-app/azure-pr-scans). ### License consumption visualization New You can now track license consumption across your tenant in Endor Labs. View your contributing developer count against your contracted limit, scan credits, and your license details. Contributing developers are categorized as verified or unverified. You can download the full contributor list and verify unverified contributors to keep your consumption count accurate. For more information, see [License consumption](/platform-administration/license). ### AI context rules for AI SAST New You can now provide AI context rules to give the AI SAST agents codebase-specific guidance about your code. The agents read these rules as reference evidence during a scan to confirm genuine vulnerabilities, reduce false positives, and account for behavior they cannot infer from the code alone. For more information, see [AI context rules](/scan/ai-sast/ai-context). ### Discontinuation of the Visual Studio Code extension Deprecation notice The Endor Labs extension for Visual Studio Code has been deprecated and is no longer supported. ### Child ticket issue type for Jira tickets Enhancement You can now choose the issue type for the child tickets that Endor Labs creates under a parent ticket when you set up a Jira integration with Endor Labs. This lets you align tickets with your team's existing Jira hierarchy instead of grouping everything under sub-tasks. Set the child ticket issue type according to the Jira issue type hierarchy. Endor Labs supports configuring the child ticket issue type for Jira Cloud only. For more information, see [Set up Jira integration](/integrations/jira#configure-jira-integration-on-endor-labs). ### Dismiss multiple notifications Enhancement You can now select multiple notifications and dismiss them together. Dismissed notifications appear in the new **Dismissed** category, where you can review them and undismiss them individually or in bulk. For more information, see [Notifications](/inventory-insights/notifications#dismiss-notifications). ### Segment-based analysis using scan profiles Enhancement You can now configure segment-based analysis directly in a scan profile. Select the languages you want under **Segment Match Languages** to scan them using segmentation and embeddings instead of resolving dependencies from a manifest. For more information, see [Configure scan profile through Endor Labs user interface](/scan/scan-profiles/configure-scanprofile-ui#configure-general-scan-profile-settings), [Configure scan profile through Endor Labs API](/scan/scan-profiles/configure-scanprofile-api), and [Configure scan profile through scanprofile.yaml](/scan/scan-profiles/configure-scanprofile-yaml). ### Change in C/C++ scan behavior Enhancement You can now scan C/C++ projects using the `--segment-match-languages=c` flag instead of `languages=c` flag to identify dependencies. For more information, see [Scan C/C++ projects with segment-based analysis](/scan/sca/c#scan-cc-projects-with-segment-based-analysis). ### Exploit and remediation details for AI SAST findings Enhancement You can now view exploit reproduction and remediation details for high and critical severity findings from the AI SAST detection agent. The exploit reproduction shows the exploit path, steps to reproduce, and a sample payload, and the remediation provides a recommended fix with a unified diff. This helps you confirm that a finding is genuinely exploitable and apply a targeted fix faster, so you spend less time triaging and more time resolving real risk. For more information, see [AI SAST detection agent](/scan/ai-sast/detection-agent#view-ai-sast-detection-agent-findings). # June 2026 Source: https://docs.endorlabs.com/releasenotes/june-2026/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Discontinuation of GitHub Cloud App Deprecation notice The standard GitHub Cloud App onboarding flow is deprecated. New projects should use [GitHub Cloud App Pro](/setup-deployment/scm-integrations/github-app). While existing projects using the standard app will continue to be scanned, we recommend [migrating to GitHub Cloud App Pro](/setup-deployment/scm-integrations/github-app/migrate-to-github-app-pro). ### Google Artifact Registry (GAR) support New You can now configure Endor Labs to authenticate with GAR for agentless dependency scanning of private npm, Maven, Gradle, and PyPI packages. Endor Labs generates short-lived OAuth2 access tokens automatically at scan time from a service account key, eliminating the need for long-lived static credentials. For more information, see [Configure integration with Google Artifact Registry](/integrations/package-managers/google-artifact-registry). ### Direct integration with Package Firewall New You can now configure the Package Firewall using direct integration, which routes package installation requests through the firewall without relying on an intermediary registry such as JFrog Artifactory. The firewall evaluates each request against the Endor Labs malware database and your configured Package Firewall policies to block, warn, or allow the installation. For more information, see [Configure the Package Firewall with direct integration](/integrations/package-firewall/direct-integration). ### Git-based dependencies Beta New Endor Labs now resolves private Git-based dependencies hosted outside the repository being scanned, including those in a different organization, workspace, or project. Configure credentials for these repositories in the Git-based dependency integration to improve dependency resolution and reachability analysis. If an existing SCM integration already has access to these repositories, Endor Labs reuses those credentials. For more information, see [Git-based dependencies](/integrations/package-managers/git-based-dependencies). ### OSS Coverage dashboard Beta New You can now use the OSS Coverage dashboard to get a centralized view of open source coverage across your namespace. You can see how Endor Labs resolves dependencies and performs reachability analysis on your scanned projects. The dashboard groups coverage gaps by root cause, and each error links to the full scan log so you can investigate and fix scan failures. For more information, see [OSS coverage](/inventory-insights/dashboards/oss-coverage) ### AI SAST detection agent New Endor Labs now offers an AI SAST detection agent that goes beyond traditional rule-based scanners. Instead of just matching patterns, it uses AI and the full repository context to find security issues that rules alone would miss, such as business logic flaws and broken access control. You can run this scan using endorctl, your CI/CD pipelines, or SCM integrations For more information, see [AI SAST](/scan/ai-sast) and [AI SAST detection agent](/scan/ai-sast/detection-agent). ### AI SAST PR scans, diff scans, and skill scanning New Endor Labs now offers the following AI SAST capabilities: * **PR scans**: Run AI SAST on pull requests to scan the code changes, surface the findings the PR introduces, and post them as PR comments. * **Local diff scans**: Run AI SAST on your uncommitted local changes to catch issues before you open a pull request. * **Skill scanning**: The AI SAST detection agent now scans AI agent skill files, such as `SKILL.md`, `AGENT.md`, and `CLAUDE.md`, for risky instructions and unsafe scripts. For more information, see [AI SAST PR scans](/scan/ai-sast/ai-sast-pr-scans) and [AI SAST detection agent](/scan/ai-sast/detection-agent). ### Dry-run mode for container scanning Enhancement You can now run `endorctl container scan` and `endorctl container registry scan` in dry-run mode using the `--dry-run` flag. Scan results are stored only in memory and not forwarded to the Endor Labs API, so you can test container scans locally without writing any data. Base image scanning is not supported in dry-run mode. For more information, see [container scanning](/developers-api/cli/commands/container). ### Exit code for baseline not found Enhancement When a PR scan cannot locate the baseline specified with `--pr-baseline`, endorctl now returns exit code 43 (`ENDORCTL_RC_BASELINE_NOT_FOUND`) instead of the generic invalid-arguments code. This makes it easier to identify and script against baseline resolution failures. For more information, see [endorctl CLI exit codes](/best-practices/troubleshooting/endorctl-exitcodes). ### Custom lock file location for JavaScript scans Enhancement You can now specify an exact lock file path for JavaScript and TypeScript scans using the `ENDOR_JS_LOCK_FILE_PATH` environment variable. This is useful when the lock file does not live at the package directory or repository root. For more information, see [Specify a custom lock file location](/scan/sca/javascript#specify-a-custom-lock-file-location). ### Maven support for the Package Firewall Enhancement You can now configure the Package Firewall for Maven to route Java dependency requests through Endor Labs and block known malicious packages. Maven is supported for both JFrog Artifactory and direct integration. For more information, see [Configure the Package Firewall with JFrog Artifactory](/integrations/package-firewall/jfrog-artifactory) and [Configure the Package Firewall with direct integration](/integrations/package-firewall/direct-integration). ### Vulnerability detection in Package Firewall policies Enhancement You can now set a CVSS severity threshold in your Package Firewall policy to block or warn on package versions that have a known vulnerability. For more information, see [Package Firewall policy](/platform-administration/policies/package-firewall-policies). ### Test dependencies in SBOM and VEX exports Enhancement By default, test dependencies are excluded from SBOM and VEX exports. You can now include them by selecting **Include test dependencies** during CycloneDX or SPDX export. For more information, see [Export SBOMs and VEX](/inventory-insights/sbom/exporting-sboms). ### Custom headers for webhook notification targets Enhancement Webhook notification targets now support custom HTTP headers for passing vendor-specific API keys required by your webhook receiver. You can configure up to 20 headers per target, and Endor Labs sends them on every webhook request irrespective of the authentication method. For more information, see [Set up integrations using webhooks](/integrations/webhooks). ### Harbor support for container registry scanning Enhancement Endor Labs now supports container scanning with Harbor registries. You can scan images from both cloud-hosted and self-hosted Harbor instances. For more information, see [Container registry scanning](/scan/containers/container-registry-scan). # March 2026 Source: https://docs.endorlabs.com/releasenotes/march-2026/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Export findings to Wiz New Endor Labs now supports exporting SCA and SAST findings to Wiz after scheduled scans on the default branch. Findings map to Wiz enrichment schemas and appear in the Wiz Security Graph so you can correlate code risk with cloud context. For more information, see [Export findings to Wiz](/integrations/data-exporters/export-to-wiz). ### Endor Labs Skills Beta New Endor Labs Skills are pre-built AI agent instructions that automate common security workflows using `endorctl`. Skills provide structured prompts that guide your AI coding assistant through tasks like installing and configuring `endorctl`, authenticating with identity providers, scanning repositories for vulnerabilities, and running secrets and SAST scans. Skills are available for Claude Code and Cursor. For more information, see [Skills](/setup-deployment/skills). ### Scala Bzlmod support for Bazel repositories New Endor Labs now supports software composition analysis for Scala projects in Bazel repositories that use Bzlmod for external dependency management. Bzlmod support requires Bazel aspects with `rules_scala` >= 5.0.0. For more information, see [Bazel](/scan/bazel) and [Bazel Aspects](/scan/bazel/bazel-aspects). ### Bitbucket Data Center App PR scans Beta New The Endor Labs Bitbucket Data Center App now supports automated pull request scanning for security vulnerabilities, policy violations, and exposed secrets. You can also configure PR comments directly on your pull requests when issues are detected, helping developers address security concerns before merging code. For more information, see [Bitbucket Data Center App PR scans](/setup-deployment/scm-integrations/bitbucket-datacenter-app/bitbucket-datacenter-pr-scans). ### Snooze findings New You can now snooze findings to temporarily dismiss them and choose when they should reappear, making it easier to defer action on findings without creating permanent exception policies. For more information, see [Snooze findings](/inventory-insights/findings#snooze-findings). ### Dismiss findings using ignore files New You can use an ignore file in your repository to exclude specific findings from scan results. The file is read during a scan and applies only to the repository version that contains it. Entries that match the file are excluded from the findings view and do not trigger action policies. For more information, see [Dismiss findings using an ignore file](/inventory-insights/findings#dismiss-findings-using-an-ignore-file) and [Allow ignore files to dismiss findings](/platform-administration/configure-system-settings#allow-ignore-files-to-dismiss-findings). ### Container registry scanning Beta New Endor Labs now supports scanning container images directly from container registries. Use `endorctl container registry` commands to: * Discover container images across repositories. * Apply filters to control the scan scope. * Create and reuse scan plans for repeated scans. For more information, see [Container registry scanning](/scan/containers/container-registry-scan). ### Package Firewall Beta New Endor Labs introduces **Package Firewall**, which inspects package requests during installation and blocks packages identified as malware in real time. Package Firewall integrates with JFrog Artifactory to route package traffic through the firewall before packages are downloaded. Malicious packages are blocked before they reach developer environments or CI pipelines. For more information, see [Package Firewall](/package-firewall). ### Rush monorepo support for JavaScript and TypeScript New Endor Labs now offers support for scanning JavaScript and TypeScript projects in Rush monorepos by resolving dependencies from `rush.json` and the centralized lock file. For more information, see [Scan Rush monorepos](/scan/sca/javascript#scan-rush-monorepos). ### Endor Labs MCP server support for additional platforms Beta Enhancement The Endor Labs MCP server now supports Claude Code, OpenAI Codex, Devin, Augment Code, and IntelliJ IDEA, in addition to the previously supported Cursor, Visual Studio Code, and Gemini CLI platforms. You can integrate the MCP server into your preferred AI-powered development workflow to scan code in real-time and catch security issues before they reach production. For more information, see [MCP Server](/setup-deployment/mcp). **Generate a Dockerfile based on auto detected toolchains** New You can now use the `endorctl toolchains docker` command to generate a Dockerfile with endorctl and the build tools your project needs. The command automatically detects toolchains in your repository. You can then build the image, mount your repository into the container, and run the scan inside the container instead of on the host. Use this when your machine lacks build tools or when you need reproducible scans across environments. For more information, see [Scan with `endorctl toolchains docker`](/scan/scan-profiles/endorctl-docker). # May 2026 Source: https://docs.endorlabs.com/releasenotes/may-2026/index We are excited to introduce the latest features and enhancements in Endor Labs. ### License Inventory Beta New Endor Labs now provides a centralized view of open source licenses in your namespace, allowing you to review license details and project usage, edit incomplete dependency license data, and generate Notice reports for software distribution. For more information, see [Licenses](/inventory-insights/licenses). ### Bazel support for TypeScript projects New Endor Labs now supports Bazel scans for TypeScript projects with [rules\_ts](https://github.com/aspect-build/rules_ts). Scan `ts_project` and `ts_project_rule` targets. Both the WORKSPACE model and Bzlmod are supported with Bazel aspects. Requires `rules_ts` >= 1.0.0. For more information, see [Bazel](/scan/bazel) and [Bazel Aspects](/scan/bazel/bazel-aspects). ### Container inventory New Endor Labs now introduces **Container Inventory** which provides a centralized view of all container images across your namespace, including shared base images and application images. It helps you track where the images are used, understand relationships between them, and identify potential risk exposure. For more information, see [Container findings](/scan/containers/container-findings). ### Bitbucket Cloud App authentication with email and API token Enhancement Endor Labs now supports connecting the Bitbucket Cloud App with an Atlassian account email and API token. For more information, see [Deploy Endor Labs Bitbucket App in Bitbucket Cloud](/setup-deployment/scm-integrations/bitbucket-cloud) and [Create an API token](/setup-deployment/scm-integrations/bitbucket-cloud/bitbucket-cloud-pr-scans#create-an-api-token). ### Filter findings by discovery type Enhancement You can now filter findings by how a dependency is discovered using the Discovery type attribute filter. This gives you better visibility into dependency origins if it was through manifest, phantom, and segment match types. For more information, see [Finding attributes](/inventory-insights/findings#finding-attributes). ### Dependency file location visualization for C/C++ packages Enhancement C/C++ scans now show dependency file locations as a visualization for each matched dependency. Expand the tree to see which source paths led to its identification. For more information, see [Scan C/C++](/scan/sca/c#view-dependency-file-locations). ### Create Jira issues from Findings Enhancement You can now create Jira issues manually from Findings for one or more findings. This allows you to act on findings that are not covered by an existing action policy, without waiting for a scheduled scan. Every issue created is recorded in **Notifications** as an **On-demand notification**. For more information, see [Create Jira issues from Findings](/inventory-insights/findings#create-jira-issues-from-findings). ### Custom lock file location for JavaScript scans New You can now specify an exact lock file path for JavaScript and TypeScript scans using the `ENDOR_JS_LOCK_FILE_PATH` environment variable. This is useful for monorepos, nested projects, and custom build setups where the lock file does not live at the package directory or repository root. The variable applies to npm, Yarn, pnpm, and Lerna projects and takes precedence over `ENDOR_JS_USE_ROOT_DIR_LOCK_FILE`. For more information, see [Specify a custom lock file location](/scan/sca/javascript#specify-a-custom-lock-file-location). ### Jira integration enhancements Enhancement Endor Labs Jira integration now includes the following updates: * You can now use scoped API tokens for the Jira integration, limiting token access to only the permissions required and improving token tracking and management. * You can configure the Jira integration using a service account, keeping credentials independent of individual users. For more information, see [Jira integration with Endor Labs](/integrations/jira). ### Package Firewall policy Enhancement Endor Labs now offers Package Firewall policies, giving you finer control over package installations beyond malware detection. Configure criteria such as restricted licenses and minimum package age to determine when the Package Firewall blocks or warns on package installations. You can also define exceptions to allow specific packages or version ranges to bypass all Package Firewall checks. For more information, see [Package Firewall policy](/package-firewall/policy). ### Chainguard images support in container scanning Enhancement Endor Labs now supports container scanning with OS reachability and instrumented reachability for Chainguard application images. For more information, see [Container scanning](/scan/containers). ### Package Firewall role Enhancement You can now create a **Package Firewall User** role through the Endor Labs application to authenticate to Package Firewall. For more information, see [Authorization roles](/platform-administration/rbac/authorization-roles). ### Go support in Package Firewall Enhancement You can now use the Package Firewall to block malicious Go modules during installation. Set up a Go remote repository in JFrog Artifactory to route module requests through the Package Firewall. For more information, see [Package Firewall](/package-firewall). ### Deleted findings in scan history Enhancement You can now view findings resolved by a scan from scan history under **Deleted Findings**. Each row shows the finding name, severity, category, when it was first detected, and attribute tags. For more information, see [Scan history](/inventory-insights/scan-history). ### SAST and secret finding location in finding logs Enhancement SAST and secret finding logs now include the file location where the finding was detected. This helps you track these findings and correlate them with specific code locations across scans. For more information, see [Scan history](/inventory-insights/scan-history). # April 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/april-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Endor Labs App for Bitbucket Cloud Beta New Endor Labs now provides an app that you can use to onboard your Bitbucket Cloud workspace and projects, and continuously monitor them in Endor Labs. The Bitbucket Cloud repositories in the projects are scanned every 24-hours, and you can initiate a rescan according to your convenience. For more information, see [Endor Labs App for Bitbucket Cloud](/setup-deployment/scm-integrations/bitbucket-cloud). ### Endor Labs App for Bitbucket Data Center Beta New Endor Labs now provides an app that you can use to onboard your Bitbucket Data Center host and projects, and continuously monitor them in Endor Labs. The Bitbucket Data Center repositories in the projects are scanned every 24-hours, and you can initiate a rescan according to your convenience. For more information, see [Endor Labs App for Bitbucket Data Center](/setup-deployment/scm-integrations/bitbucket-datacenter-app). ### Updated navigation for OSS Packages Enhancement Endor Labs has updated the **OSS Packages** navigation. You can now access explore **OSS Packages** through the left sidebar, providing a more direct navigation. For more information, see [Search for open source packages](/discover/open-source-packages). ### Pull Request remediation support for .NET Enhancement Endor Labs GitHub App (Pro) now supports PR remediation for .NET, alongside Java, JavaScript, Go, and Python. Automated remediation is available for dependencies managed through `*.csproj`. For more information, see [Pull requests remediation in GitHub](/risk-remediation/automated-pull-requests) # Archive releases Source: https://docs.endorlabs.com/releasenotes/previous-releases/archive/index ## Release 1.5.251 ## New Features ### Prioritize vulnerabilities with C# call graphs Users can now use call graphs in the Endor Labs application to analyze the dependencies and relationships among functions in .NET C# projects. * Endor Labs generates the call graphs for your **C#** projects and identifies functions or methods with known vulnerabilities or potential security issues. * Users can examine the call graph to identify the functions that directly or indirectly call the vulnerable functions by tracing the paths of execution. * Users can prioritize the vulnerabilities based on their severity, threat levels, and application importance. Call graphs assist users in comprehending the potential consequences and enable them to prioritize the resolution of vulnerabilities that are more likely to result in additional exploitation. ### View policy violations in PR comments Users can view policy violations in their source code before committing the code to the repository during the automated pre-commit checks. The information is included as comments on the respective pull requests. Users can easily identify and take remedial measures early in the development life cycle. Based on the actions configured in your action policy, the workflow is designed to either warn you or fail the build based on the severity of these policy violations. ### Configure webhooks Integrate Endor Labs with webhooks to send Endor Labs notifications to webhooks and pass information to any third-party applications such as Slack, Microsoft Teams, and many more. Users can monitor the webhook channels to investigate and take remedial measures. With a webhook integration, you can configure Endor Labs to send information to the webhook as an HTTP POST request as soon as a notification is generated. You can also modify the key format and value associated with the notification in the payload. ### Perform organization-wide supervisory scans Use the Endor Labs [Jenkins pipeline](https://github.com/endorlabs/jenkins-org-scan) to scan all the repositories in your organization at once and view consolidated findings. This pipeline runs on your organization's Jenkins infrastructure and enables administrators to run organization-level supervisory scans easily. It is designed to work in GitHub Cloud and GitHub enterprise server environments. ## Enhancements ### Detect malware packages When software applications depend on malicious packages, the confidentiality, integrity, and availability of systems and data belonging to software development organizations or to application end-users is compromised. Endor Labs now detects application dependencies that are known to be malicious, as reported by the Open Source Vulnerabilities (OSV). Use the newly introduced **Malware** category on the **Findings** page to filter and view malware findings. Users can prioritize, and take necessary remedial actions such as patching or replacing the affected packages. ### Configure private NuGet repositories Endor Labs provides the support to integrate with private NuGet package repositories, in addition to scanning public C# projects and repositories. Users can configure this integration from **Integrations** > **NuGet**. Endor Labs will fetch the resources from the authenticated endpoints and perform the scan. ### Secrets enhancements * **Scan for secrets in pre-commits** - Users can scan for secrets in the code before committing the code to the code repository during the automated pre-commit checks. This helps identify and remove sensitive information from the code files early in the development life cycle. * **Secrets deduplication** - A single secret may exist at multiple places in your code or repository. Duplicate secrets increase the attack surface and the risk of unauthorized access. Managing duplicate secrets can be complex and error-prone. Endor Labs intelligently categorizes instances of identical secrets found within your application components and repositories and raises a single finding so that you can manage them efficiently. ## Release 1.5.194 ## Enhancements ## Support for private Composer package repositories In addition to scanning public PHP projects and repositories, Endor Labs provides the support to integrate with private Composer package repositories. Users can configure this integration from **Integrations** > **Packagist**. Endor Labs will fetch the resources from the authenticated endpoints and perform the scan. ## Release 1.5.171 We are excited to introduce you to the latest version of Endor Labs and endorctl - v 1.5.171. This release includes new features. ## New Features ## Support for scanning secrets in code Endor Labs scans your code files and repositories for secrets such as API keys, registration tokens, client secrets, client IDs, access tokens, bearer tokens, refresh tokens, or registration tokens of multiple popular services such as GitHub, Git Lab, AWS, Dropbox, Adobe, Atlassian, Bitbucket, Coinbase, Databricks, and many more services. Using [Endor Labs' secrets scan](/scan/secrets), users can: * View findings for secrets exposed in the code and take remedial actions based on their severity. * Detect valid and active secrets in their code repositories and immediately secure them. * Perform the endorctl scan to audit their codebase regularly for secrets and take necessary mitigation measures. ## Release 1.5.159 We are excited to introduce you to the latest version of Endor Labs and endorctl - v 1.5.159. This release includes new features and enhancements. ## New Features ## Support for PHP project scanning Endor Labs further extends its language scanning capabilities by incorporating support for [PHP](/scan/sca/php). In addition to the current support for Java, JavaScript, Rust, Python, Go, Ruby, .NET C#, and Scala, users can now scan and monitor their PHP projects. Endor Labs scans PHP projects and resolves dependencies by analyzing both composer.json and composer.lock files. Users can view finding policy violations and dependency graphs. Using Endor Labs, users can gain significant insights into the structure and relationships of their PHP project's dependencies, aiding in managing dependencies effectively, identifying potential issues, and ensuring a well-organized and maintainable codebase. ## Enhancements ## Support for Ruby private registry In addition to scanning public Ruby projects and repositories, Endor Labs provides the support to integrate with private Ruby registries that are not available publicly. Users can configure this integration from **Integrations** > **RubyGems**. Endor Labs will fetch the resources from the authenticated endpoints and perform the scan. ## Release 1.5.131 We are excited to introduce you to the latest version of Endor Labs and endorctl - v 1.5.131. This release includes new features. ## New Features ## Support for Scala language scan Endor Labs further extends its language scanning capabilities by incorporating support for [Scala](/scan/sca/scala) projects. In addition to the current support for Java, JavaScript, Rust, Python, Go, Ruby, and .NET C#, users can now scan and monitor their Scala projects managed by sbt. Endor Labs scans Scala projects by executing sbt plugins and inspecting the build.sbt file to retrieve information about direct and transitive dependencies. Using Endor Labs, users can gain significant insights into the structure and relationships of their Scala project's dependencies, aiding in managing dependencies effectively, identifying potential issues, and ensuring a well-organized and maintainable codebase. ## Release 1.5.117 We are excited to introduce you to the latest version of Endor Labs and endorctl - v 1.5.117. This release includes new features and enhancements. ## New Features ## Support for .NET scan Endor Labs further extends its language scanning capabilities by incorporating support for the [.NET C# framework](/scan/sca/dotnet). In addition to the current support for Java, JavaScript, Rust, Python, Go, and Ruby, users can now scan and monitor their .NET **C#** projects and repositories. Endor Labs leverages the packages.lock.json file to monitor the packages for dependencies and discovers unresolved, resolved, direct, and transitive dependencies. Users will also be able to view finding policy violations and dependency graphs. Organizations can maintain secure .NET development and runtime environments while designing, coding, debugging, testing, and deploying complex C# projects and applications. ## Endor Labs extension for Visual Studio Code Developers can now use Endor Labs directly from their Visual Studio Code's Integrated Development Environment (IDE). The Endor Labs extension scans your repositories and highlights issues that may exist in the open-source dependencies. The extension helps developers fix code at its origin phase and during the early stages of development. They can successfully perform early security reviews and mitigate the need for expensive fixes during later stages. ## Enhancements ## Use Python call graphs for vulnerability prioritization Users can now use call graphs in Endor Labs application to analyze the dependencies and relationships among functions in Python projects. * Endor Labs generates the call graphs for your Python projects and identifies functions or methods with known vulnerabilities or potential security issues. * Users can examine the call graph to identify the functions that directly or indirectly call the vulnerable functions by tracing the paths of execution. * Users can prioritize the vulnerabilities based on their severity, threat levels, and application importance. Call graphs assist users in comprehending the potential consequences and enable them to prioritize the resolution of vulnerabilities that are more likely to result in additional exploitation. ## EPSS probability filter for findings Users can now use the new Exploit Prediction Scoring System **EPSS probability** filter on the **Findings** page to refine their findings search results by the [EPSS](https://www.first.org/epss/) score range. ## View Notifications Users can now view the Jira tickets created for action policies in **Notifications** on the sidebar. Users have the ability to observe specific information such as the status of tickets (whether they are open or closed), the associated action policy, and other important details. This aids in seamless troubleshooting and identification of both unresolved and resolved issues. ## Release 1.5.104 We are excited to introduce you to the latest version of Endor Labs and endorctl - v 1.5.104. This release comes with the following new features. ## New Features ## Integrate Endor Labs with Jira [Integrate Endor Labs with Jira](/integrations/jira) and receive alert notifications for your action policies in your Jira accounts. With this integration, administrators can automate the process of generating Jira tickets within their organization's existing security workflows. Administrators can choose to raise bugs or create tasks in Jira and notify required people about any failures. ## Set up SAML integration for Endor Labs Set up SAML integration on Endor Labs, using an Identity Provider (IdP) that supports Security Assertion Markup Language (SAML), such as Okta, Microsoft Active Directory Federation Services (AD FS), Azure Active Directory (AD), Google, or OneLogin. Administrators can use their existing Single Sign On (SSO) process in their organization and allow their users to seamlessly sign in to Endor Labs without providing credentials. ## Support for Ruby language scan Endor Labs broadens its language scanning capabilities by incorporating support for the [Ruby programming language](/scan/sca/ruby). In addition to the current support for Java, JavaScript, Rust, Python, and Go, users can now scan and monitor their Ruby projects and repositories. Endor Labs monitors the packages for dependencies and discovers unresolved, resolved, direct, and transitive dependencies. Users will also be able to view finding policy violations and dependency graphs. ## Release 1.5.43 Endor Labs and endorctl version 1.5.43 includes: * A portfolio level view of all findings across your repositories * SARIF output format support for GitHub Integrations * Custom identity provider claim requests to allow for custom attribute based access controls * Support for Gradle version 8 * The ability to ask natural language questions of open source software via DriodGPT * The ability to configure, enable and disable your organizations desired findings ## New Capabilities ### A portfolio level view of all findings across your repositories Organizations are now able to review all findings across their entire portfolio. Each project monitored by Endor Labs is aggregated into a global view of findings so that organizations can easily search for updates. ### SARIF output format support for GitHub integrations In CI pipelines developers can now upload their findings to GitHub via a SARIF output of their findings. This enables developers to not have to leave GitHub to review detailed results. ### DroidGPT Organizations can now ask natural language questions about open source software using DroidGPT. As part of Endor Lab's open source explorer organizations can now ask questions like "What is the most secure package for json to csv conversion?" ## Release 0.5.126 Endor Labs and endorctl version 0.5.126 includes: * Support for policy actions in CI pipelines (Beta) * Environmental configuration checks for scanning * Significant performance improvements * Improved sorting and filtering for findings ## New Capabilities ### Support for policy actions in CI pipelines (Beta) Endor Labs now enables users to configure policy that returns an error in CI pipelines. This can allow users to fail CI checks when a policy is violated to enforce organizational governance policy. Endor Labs comes with out-of-the-box policy templates to enable teams to configure policy on known vulnerabilities, outdated, unmaintained and unused software dependencies. ### Environmental checks for scanning Endor Labs now helps ensure that your machine is well setup for scanning by providing inline configuration checks on commands. If your host is not properly configured or does not have the required software to perform a given scan or command, the command line utility, endorctl will inform you. ### Improved sorting and filtering for findings Findings can now be filtered and displayed based on categories to help users better report on what they care about and focus their attention. Supported categories include: * Vulnerabilities * Supply Chain Risk * License Compliance * Supply Chain Posture Management Risk * General Security Risks * General Operational Risks ## Release 0.5.100 Endor Labs and endorctl version 0.5.100 includes: * Scanning for JavaScript and Python is generally available. ## New Capabilities ### General Availability of Python and JavaScript Support Endor Labs support for JavaScript and Python Language Scanning is now generally available. ## Release 0.5.80 Endor Labs and endorctl version 0.5.80 includes: * Support for GitLab and Bitbucket source control repository scanning * Support for Keyless Authentication in GCP with workload identity ## Major Changes * Previously, Endor Labs supported remote cloning of GitHub based repositories. This option has been removed. Only locally cloned repositories are supported. ## New Capabilities ### Support for GitLab and Bitbucket based Endor Labs now supports the ability to scan source control repositories hosted in GitLab and Bitbucket. ### Keyless Authentication for GCP Endor Labs now supports the ability to leverage keyless authentication for workload identity federation in Google Cloud. ## Release 0.5.50 Endor Labs and endorctl version 0.5.50 includes: * Support for parallel language scanning * Identification of potential typos in dependencies * Support to export Vulnerability Exploitability eXchange (VEX) data for packages * Dependency License Identification * Support for user authorization roles ## New Capabilities ### Parallel Language Scanning Support Endor Labs now supports the ability to scan different languages in parallel to accelerate scan speed and performance. ### Identification of potential typos in dependencies Endor Labs now supports the ability to monitor and alert on dependencies imported as typos of much more widely used dependencies in your environment. ### Export Vulnerability Exploitability eXchange (VEX) for packages Endor Labs now enables software producers to export VEX documents with automated triage of unreachable vulnerable functions to support software consumer vulnerability triage efforts. ### Dependency license identification support Endor Labs now identifies the license associated with an associated software dependency for open source license management. ### Authorization Roles Endor Labs now comes with out-of-the-box authorization roles for platform users. Authorization roles include: * Policy Editor - The policy editor role allows users to edit policy. * Code Scanner - The code scanner role allows users with this permission to scan code. This is the minimum role for a CI/CD based service account. * Read-only - The read only permission gives users full read only access to Endor Labs. * Admin - The Admin permission gives users full read and write access to Endor Labs. ## Major Bug Fixes Resolved in version 0.5.50 * Previously, Endor Labs failed to scan a repository and identify packages within a repository if the repository was cloned with a shallow Git clone. This has been addressed in 0.5.50. ## Release 0.5.40 Endor Labs and endorctl version 0.5.40 includes: * Support for EAR and WAR File scanning for Maven * Fat/Uber JAR support for Maven * Vulnerable function reachability analysis * Call path visualizations for findings ## New Capabilities ### Enhanced Java Scanning Support When scanning Java based web applications using EAR, WAR and Uber JAR files, Endor Labs now builds a bill of materials for these packages and is able to successfully perform static analysis for vulnerability prioritization. ### Vulnerable function reachability analysis Endor Labs now identifies if a vulnerable function associated with a known vulnerability is reachable through static analysis in a provided Java package. ### Call Path Visualizations Endor Labs will now display reachable function paths to dependencies and functions associated with known vulnerabilities. ## Release 0.5.31 Endor Labs and endorctl version 0.5.31 includes: * The ability to export a Software Bill of Materials (SBOM) for a specified software package * Windows support for endorctl * Beta support for Gradle with Java * Authorization Policies for enhanced access control with Endor Labs ## New Capabilities ### Support for exporting SBOMs SBOMs may now be generated for any supported software package that you create in CycloneDX format. Endor Labs supports XML and json formats for CycloneDX and by default exports in CycloneDX 1.4. ### Windows Support for `endorctl` Endor Labs now supports Windows for the endorctl binary. This allows Windows users who previously were using the Endor Labs Docker image to migrate to a supported binary on their native platform. ### Support for Gradle Endor Labs now supports Gradle 7 and above as a build tool for Java packages. Java packages using Gradle 7 or above can now successfully have their dependencies resolved and generate call graphs for their packages. ### Authorization Policies Endor Labs users can now set granular authorization policies for each supported identity provider. Users may now specify a unique user identity such as a GitHub handle or Google Workspace email address to authorize users. Authorization rules may also be timeboxed to ensure that a user only has access to Endor Labs for a predefined time. Previously, new users could only be authorized by requiring them to be sent an email invitation to the platform. ## Major Bug Fixes Resolved in version 0.5.31 **Release date**: 28 October, 2022 * Previously, some packages failed dependency resolution due to a nil pointer exception. This resolution error has been addressed. * Previously, when filtering findings based on their attributes filters only respected the current page being searched on. This issue has now been addressed. * Previously, some findings that had an upstream patch available were displayed as having a fix unavailable. This issue has been addressed. # August 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/august-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Discontinuation of CI/CD tool scanning Breaking change CI/CD tool scanning functionality is being deprecated and will be discontinued by September 15, 2025. This change does not affect the scanning of GitHub Action dependencies. ### AI security review New AI security review provides automated code review capabilities using artificial intelligence to identify potential security issues in your code base. You can set up AI security review to review pull requests and raise findings for security issues. For more information, see [AI security review](/secure-ai-coding/ai-security-review). ### First-party code dashboard New The first-party code dashboard provides a comprehensive view of the vulnerabilities in your codebase from a SAST and secrets perspective. For more information, see [First-party code dashboard](/inventory-insights/dashboards/first-party-code). ### Container end of life dependency finding policy New You can now enable the **End of Life Container Dependencies** finding policy to raise findings for OS-level packages and components in container images that have reached end of life. For more information, see [Container finding policies](/platform-administration/policies/finding-policies/container-policies). ### Malware policies New Endor Labs now offers improved malware detection with detailed malware reasoning, broader coverage, and timely warnings before malicious packages disappear from registries. You can use the following new malware focused policies: * **Malware finding policy**: Enable OSS finding policy to identify known malicious code or suspicious patterns in dependencies and raise findings for them. * **Malware action policy**: Create an action policy from the malware template to define how to handle malware findings. * **Malware exception policy**: Create an exception policy to apply exceptions to malware findings under defined conditions and exclude them from action policies. For more information, see [OSS finding policy](/platform-administration/policies/finding-policies/oss-policies), [Malware action policy](/platform-administration/policies/action-policies/templates#malware), and [Malware exception policy](/platform-administration/policies/exception-policies/templates#malware). ### Export SBOM in SPDX format New You can now export Software Bill of Materials in the industry standard SPDX format, with support for both `json` and `tag-value` output formats, making it easier to integrate SBOMs into existing compliance, auditing, and security workflows. For more information see [Export SBOM in Endor Labs](/inventory-insights/sbom/exporting-sboms#export-an-sbom-as-spdx). ### Support for pull request scans in GHAS SARIF exporter Enhancement The GHAS SARIF exporter now supports pull request scans for GitHub App (Pro). If you have enabled pull request scans in your GitHub App, the GHAS SARIF exporter exports the findings for each pull request. You can view the findings for the pull request in GitHub Advanced Security. For more information, see [Export findings to GitHub Advanced Security](/integrations/data-exporters/export-to-ghas). ### Azure OpenAI model detection Enhancement Endor Labs extends AI model detection to include Azure OpenAI, surfacing detected models as dependencies during scans. Azure OpenAI models are detected but not scored, as provider metadata is limited. For more information, see [AI model detection](/secure-ai-coding/ai-model-discovery). ### Scan container image tarball Enhancement You can now scan container images saved as tarball files using `endorctl`. This helps you analyze dependencies, generate SBOM details, and review security findings for container images that are not directly accessible from a registry. For more information, see [Scan container image tarball](/scan/containers#scan-container-image-tarball). ### Search for malware in Vulnerability Database Enhancement You can now use the MAL identifier to search for known malware in the Endor Labs vulnerability database and quickly identify malicious packages alongside existing vulnerabilities. For more information, see [Endor Labs vulnerability database](/discover/vulnerability-db). # December 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/december-2024/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Upgrade to endorctl version 1.6.734 or later for container scans Breaking change Endor Labs has notably improved container scanning, enhancing the accuracy of findings. As a result, container scans performed with older endorctl versions sometimes yield different or no results. To ensure accurate scans, upgrade endorctl to version 1.6.734 or higher. Run `endorctl --version` to check your current version. For instructions on upgrading endorctl, see [Install Endor Labs on your local system](/introduction/getting-started#install-endorctl). ### Upgrades and remediation support for .NET, Kotlin, and Scala projects Enhancement Endor Labs upgrade impact analysis now extends its capabilities to support Kotlin, Scala, and .NET projects, complementing the existing support for Python and Java to streamline dependency upgrades across more languages. For more information, see [Remediation support matrix](/risk-remediation#remediation-support-matrix). ### Configure container finding policies Enhancement Container base images from untrusted sources may lack proper security audits or fail to comply with organizational standards, increasing the risk of vulnerabilities being exploited. To address this, you can now configure a finding policy to detect unauthorised base images and raise a critical finding. For more information, see [Container policies](/platform-administration/policies/finding-policies/container-policies). ### Export multiple package versions in SBOM Enhancement You can now export multiple package versions in an SBOM through the Endor Labs user interface. This feature allows aggregating multiple package versions of a project in a single SBOM file. You can choose packages and package versions of a project, which you can export as an SBOM file. For more information, see [Export an SBOM at the project level](/inventory-insights/sbom/exporting-sboms#export-an-sbom-at-the-project-level). ### My Packages removed from Endor Labs user interface **My Packages** page is no longer available on the Endor Labs user interface. Instead, you can view packages and package versions associated with a project under **Projects**. Use the package versions filter in **Projects** to filter by specific package criteria. # December 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/december-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Endor Labs MCP server Developer Edition Beta New The Endor Labs MCP server is now available in Developer Edition. You can get started without any prior configuration or Endor Labs account. The Endor Labs MNP server Enterprise Edition has also been updated to provide easier configuration and setup. For more information, see [Endor Labs MCP server](/setup-deployment/mcp). ### Endor Labs MCP server as a Gemini extension Beta New The Endor Labs MCP server is now available as a Gemini extension. You can use natural language commands to interact with the MCP server. For more information, see [Endor Labs MCP server as a Gemini extension](/setup-deployment/mcp/gemini). ### Enhanced dependency graph visualization Enhancement The dependency graph now offers improved rendering performance and enhanced node interactions, making it easier to visualize and explore complex dependency trees. For more information, see [View dependency graph](/inventory-insights/dependencies#view-dependency-graph). # February 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/february-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Endor patch dashboard New The Endor Patch dashboard demonstrates the impact of Endor Patches and request patches directly within the product. It provides: * A list of the most impactful dependencies affecting applications, with patches available for evaluation. * Existing patches that can be used immediately upon purchase, along with their organization-wide impact. * A visualization of how multiple patches would affect an application portfolio. * Filters for reachability and severity to refine results easily. * The dashboard makes it easier to assess, justify, and act on patching needs efficiently. For more information, see [Endor patch dashboard](/inventory-insights/dashboards/endor-patches). ### View scan history New Scan History gives you a detailed view of past security scans, helping you track your project's security posture over time. With full context on individual scans, you can assess fidelity and troubleshoot issues more effectively. For more information, see [Review past scan details](/inventory-insights/projects#review-past-scan-details). ### endorctl scan CLI options New Use the following new endorctl CLI options for tagging findings and projects: * **Associate custom tags with findings**: Using the newly introduced `endorctl scan` CLI flag `--finding-tags ` you can associate a list of custom tags with findings generated for objects in your scan. You can also use these tags to search and filter findings in the Endor Labs user interface. * **Associate custom tags to your projects**: Using the newly introduced `endorctl scan` CLI flag `project-tags ` you can associate a list of custom tags to your projects. For more information, see [endorctl scan commands](/developers-api/cli/commands/scan). ### Endor Labs Azure Pipelines extension New The Endor Labs Azure Pipelines extension is now available in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=EndorLabs.endorlabs-security-scan-task). You can use the extension to seamlessly integrate Endor Labs scanning into Azure Pipeline. For more information, see [Use Endor Labs extension with Azure pipelines](/setup-deployment/ci-cd/scan-with-azuredevops#configure-azure-pipeline-to-use-endor-labs). ### Add Azure organizations to Endor Labs Enhancement You can now add Azure organizations to Endor Labs instead of individual projects. All projects under the organization are added automatically. Azure organizations and projects are mapped as managed namespaces in Endor Labs. For more information, see [Managed namespaces for Azure DevOps](/setup-deployment/scm-integrations/azure-app#managed-namespaces-for-azure-devops). ### Handle multiple requirement files with custom names in pip Enhancement Endor Labs now supports custom and multiple requirement file names while performing dependency analysis using the pip package manager. For more information, see [Handling custom and multiple requirement files in pip](/scan/sca/python#handling-custom-and-multiple-requirement-files-in-pip). ### Support for py\_images with Bazel Enhancement Endor Labs now supports scanning [py\_image](https://github.com/bazelbuild/rules_docker/blob/master/README.md#py3_image) with Bazel. For more information, see [Bazel](/scan/bazel#supported-bazel-rules-and-features). ### Labels in Jira ticket Enhancement Jira tickets created by Endor Labs now include the labels `endorlabs-scan` and `endor-severity`, making it easy to identify these tickets and the severity of the findings associated with them. For more information, see [View ticket details in Jira](/integrations/jira#view-ticket-details-in-jira). ### Enhanced findings user interface Enhancement Endor Labs has improved the user interface for findings: * Removed the **Overview tab** to simplify the findings workflow. * Moved the **Dependencies** and **Packages** tabs under **Inventory** for better organization and accessibility. # February 2026 Source: https://docs.endorlabs.com/releasenotes/previous-releases/february-2026/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Container reachability Beta New Endor Labs now supports container reachability, which determines which OS packages in a container image are used at runtime and marks them as **Reachable**, **Potentially Reachable**, or **Unreachable**. This helps you prioritize remediation for dependencies that are actually exercised during execution. Endor Labs supports two container reachability modes based on how your workload runs and its runtime dependencies. * **Basic reachability**: Profiles the container locally during the scan. Use when the application has no external dependencies. * **Instrumented reachability**: Runs the image in your real environment with an embedded sensor to capture runtime behavior. Use when the workload requires databases, queues, or other external services. For more information, see [Container reachability](/scan/containers/container-reachability) and [Instrumented container reachability](/scan/containers/instrumented-reachability). ### Bazel Bzlmod support New Endor Labs now supports Bzlmod when you use Bazel aspects. Currently, only Go and Java rulesets support Bzlmod. For more information, see [Bazel](/scan/bazel) and [Bazel aspects](/scan/bazel/bazel-aspects). For more information, see [Bazel Bzlmod support](/scan/bazel/bazel-aspects#bazel-bzlmod-support). ### Bazel aspects support New Endor Labs now supports Bazel aspects to improve dependency resolution accuracy in Bazel workspaces. Endor Labs automatically discovers and applies the appropriate rules for your project, and also supports custom aspects for projects with custom build rules. For more information, see [Bazel aspects](/scan/bazel/bazel-aspects). ### AI-powered SAST analysis New Endor Labs now supports AI-powered analysis for SAST findings to automatically classify them as true positives or false positives. The AI agent analyzes code context, traces data flows, and evaluates security controls to reduce false positives, helping security teams and developers focus on genuine security vulnerabilities. AI SAST analysis features require a Code Pro license. For more information, see [AI SAST triage agent](/scan/ai-sast/triage-agent). ### Bitbucket Cloud App PR scans Beta New The Endor Labs Bitbucket Cloud App now supports automated pull request scanning for security vulnerabilities, policy violations, and exposed secrets. You can also configure PR comments directly on your pull requests when issues are detected, helping developers address security concerns before merging code. For more information, see [Bitbucket Cloud App PR scans](/setup-deployment/scm-integrations/bitbucket-cloud/bitbucket-cloud-pr-scans). ### Search and filter notifications Enhancement You can now use search for notifications using the policy name or Jira issue key, and also apply filters to narrow down notifications by time range, projects, notification channels, or error status. This helps you quickly locate specific notifications, identify patterns across your security events, and efficiently manage notification workflows. For more information, see [Notifications](/inventory-insights/notifications). ### Updated Endor Labs user interface Enhancement Endor Labs now features a redesigned interface with updated navigation, layout, and workflows, making it easier to find and manage your security data. For more information, see [Endor Labs user interface](/introduction/endor-labs-ui). DroidGPT has been removed from the product. For AI-powered help with findings and scan errors, use the [Endor AI Chat](/secure-ai-coding/agentic-ui) in the application. ### API documentation updates Some API services are now designated as internal. As a result, they are no longer visible in the public [API documentation](/api-reference/). # January 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/january-2025/index **Version upgrade notice** Effective 21st January 2025, Endor Labs and endorctl are upgraded to version 1.7 from the previous 1.6.x series. This version upgrade reflects continuous improvements to our GitHub App and introduces a new suite of capabilities to help teams accelerate their security maturity. Policy updates and the activation of new policies are disabled by default. To allow automatic updates and enable new policies by default, see [Configure policy settings](/platform-administration/configure-system-settings#configure-policy-settings). This update does not introduce any breaking changes and requires no action on your part. You can continue using the product without any impact on compatibility or performance. We are excited to introduce the latest features and enhancements in Endor Labs. ### SAST scan with Endor Labs Beta New You can now use the Endor Labs SAST scan to examine your source code and identify potential security vulnerabilities without program execution. For more information, see [SAST scan with Endor Labs](/scan/sast). ### Detect AI models Beta New Endor Labs' scan can now detect AI models from HuggingFace used in Python projects and list them as dependencies. These models are flagged and displayed in the scan results. You can define custom policies to detect and flag models with low-quality scores, ensuring the use of secure and reliable AI models in your projects. For more information, see [Detect AI Models](/secure-ai-coding/ai-model-discovery). ### Monitor your projects using Endor Labs GitLab App Beta New You can now use the Endor Labs GitLab App to continuously monitors your projects for security and operational risk. You can use the GitLab App to selectively scan your repositories for SCA, secrets, SAST, and CI/CD tools. For more information, see [Deploy Endor Labs GitLab App](/setup-deployment/scm-integrations/gitlab-app). ### PR remediation with Endor Labs GitHub App Pro Beta New You can use the Endor Labs GitHub App (Pro) to create automated pull requests to remediate findings in your GitHub environment. When PR remediation is set up, Endor Labs creates a PR to update the manifest files with dependency version upgrades, based on a remediation policy, to address vulnerability findings. For more information, see [Pull requests remediation in GitHub](/risk-remediation/automated-pull-requests). ### Scan PRs with the Endor Labs GitHub App Beta New In addition to automatically scanning your repositories every 24 hour, Endor Labs GitHub App can now perform fully automated scanning process for all pull requests and merges initiated into the main branch. Whenever a PR is created against a repository, you can use the Endor Labs GitHub App to perform incremental scans to detect any changes in resolved dependencies that may introduce new vulnerabilities. These incremental scans are CI runs and are not monitored. You can see the results of the scan on GitHub. Based on your preferences, you can perform a quick scan or a full scan before merging the PRs into the main branch. * **Quick Scan** performs dependency resolution but does not conduct reachability analysis to prioritize vulnerabilities. The quick scan enables users to swiftly identify potential vulnerabilities in dependencies, ensuring a smoother and more secure merge into the main branch. * **Full Scan** performs dependency resolution, reachability analysis, and generate call graphs for supported languages and ecosystems. This scan enables users to get complete visibility and identifies all issues related to dependencies and call graph generation, before merging into the main branch. Full scans may take longer to complete, potentially delaying PR merges. ### arm64 Linux binaries of endorctl New endorctl is now available as arm64 binaries for Linux in addition to the existing AMD64 binaries. You can now use endorctl with arm64 flavors of Linux. For more information, see [Install endorctl on Linux](/introduction/getting-started#install-endorctl). ### Function level reachability for JavaScript/TypeScript projects Enhancement Function level reachability analysis for JavaScript/TypeScript projects is now enabled by default. This means you no longer need to manually enable it using the `ENDOR_JS_ENABLE_TSSERVER` environment variable or the `--call-graph-languages` flag. # January 2026 Source: https://docs.endorlabs.com/releasenotes/previous-releases/january-2026/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Export scan data to Amazon S3 New Endor Labs now supports exporting scan data to an Amazon S3 storage bucket for archival, compliance, or integration with other tools. The S3 exporter supports exporting findings in JSON or SARIF format. For more information, see [Export findings to S3](/integrations/data-exporters/export-to-s3). ### Send separate notifications for each finding Enhancement You can now use the **None (Notify for each Finding)** aggregation type to send separate notifications for every finding generated from the configured action policy, making it easier to track and assign individual security issues. This aggregation type is supported only for SAST and Secrets action policies. For more information, see [Aggregation types for notifications](/platform-administration/policies/action-policies#aggregation-types-for-notifications). ### Filter findings by tags in GitHub Advanced Security Enhancement Endor Labs now includes finding tags and categories in the SARIF output when exporting findings to GitHub Advanced Security (GHAS). You can use these tags to filter and identify specific types of findings in GitHub code scanning, such as reachable vulnerabilities, findings with available fixes, or findings by category, like SCA, SAST, and Secrets. For more information, see [Filter findings by tags in GitHub](/integrations/data-exporters/export-to-ghas#filter-findings-by-tags-in-github). # July 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/july-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Support for CVSS v4.0 scores New Endor Labs now supports CVSS v4.0, as an enhanced standard for vulnerability severity assessment. CVSS v4.x scores, including full vector strings and metadata are available in Endor Lab's reporting and data exports. Vanta exports continue to support only CVSS v3.x. By default, Endor Labs uses **CVSS v3.x**. You must explicitly configure the system to use **CVSS v4.x.** For more information, see [Configure CVSS score version](/platform-administration/configure-system-settings). ### Endor Labs Vulnerability Database New Endor Labs now includes a comprehensive vulnerability database to search and analyze known issues across software dependencies using CVE, GHSA, and PySEC identifiers. It maps vulnerable package versions to impacted projects and findings to support easier remediation. For more information, see [Endor Labs vulnerability database](/discover/vulnerability-db). ### SARIF export to GitHub Advanced Security New Endor Labs now supports exporting findings to GitHub Advanced Security as SARIF files. You can use GitHub Advanced Security to analyze and triage findings from Endor Labs. For more information, see [Export findings to GitHub Advanced Security](/integrations/data-exporters/export-to-ghas). ### Discover AI models Enhancement Endor Labs extends AI model detection to include external providers, listing detected models as dependencies. Hugging Face models are scored, as they are open source and provide extensive public metadata. Models from other providers are detected but not scored due to limited data. For more information, see [AI model detection](/secure-ai-coding/ai-model-discovery). ### C/C++ scan improvements Enhancement **Effective Monday, July 21, 2025**, Endor Labs is releasing new updates to the code segment analyzer and the underlying database of hashes and embeddings used in C/C++ Software Composition Analysis. If you use continuous integration workflows or perform local scans, you must update to the latest version of `endorctl` and re-run your scan with: ```bash theme={null} endorctl scan --languages=c ``` The first scan may take longer than usual, as it rebuilds the cache of code segments. You may also see differences in the results compared to previous scans. These changes improve the accuracy of dependency detection and matching. # June 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/june-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Endor Labs MCP server for IDE Alpha New Endor Labs MCP server is now available in alpha for Cursor and Visual Studio Code. The Endor Labs MCP server integrates directly into your IDE to scan code in real-time, and catch security issues before they reach production. This workflow secures both human and AI-generated code from the moment it's written. For more information, see [Endor Labs MCP Server](/setup-deployment/mcp). ### Grant support access to your tenant New You can now grant the Endor Labs support team read-only access to your tenant for a limited time. This feature enables our support team to assist you more efficiently while ensuring your data remains secure and private. For more information, see [Grant support access](/platform-administration/rbac/authorization-policies#grant-support-access). ### Finding policies for AI models Enhancement You can now configure two new finding policies and manage the use of AI models more effectively in your organization. * **Restricted AI models**: Raise a finding when a repository uses an AI model that your organization has marked as restricted or allowed only in specific contexts. * **Restricted AI model providers**: Raise a finding when a repository uses an AI model from a provider that is restricted based on your organization’s policy. For more information, see [Detect AI models](/secure-ai-coding/ai-model-discovery#detect-ai-models). ### Manually upgrade finding policies Enhancement You can now upgrade a finding policy when a new version is available. Policy upgrades may include changes such as updated Rego code, new fields, parameters, or tags. After upgrading, you cannot revert the policy to its previous version. For more information, see [Upgrade a finding policy](/platform-administration/policies/finding-policies#upgrade-a-finding-policy). ### Resolving package names from prop files Enhancement endorctl now evaluates MSBuild properties from files like `Directory.Build.props`, enabling resolution of package names and versions defined using variables. For more information, see [Resolving package names from props files](/scan/sca/dotnet#resolving-package-names-from-props-files). ### Group findings by dependency Enhancement Findings in the **SCA**, **Vulnerability**, and **Container** categories are now grouped by **Dependency** by default, making it easier to review your scans. For more information, see [View findings](/inventory-insights/findings). ### AI model discovery in Endor Labs monitoring scans Enhancement Endor Labs now automatically detects AI models during SCA scans when using the GitHub App, Bitbucket App, Azure DevOps App, and GitLab App. You can view AI models from the **AI Inventory**. For more information, see [View AI model findings using Endor Labs GitHub App](/secure-ai-coding/ai-model-discovery#view-ai-model-findings-through-monitoring-scans). ### Components field support for Jira tickets Enhancement You can now configure the Jira integration in Endor Labs to automatically populate the **Components** field in Jira tickets for both company-managed and team-managed Jira projects. For more information, see [Integrate Jira with Endor Labs](/integrations/jira#configure-jira-integration-on-endor-labs). ### Exclude all child namespaces Enhancement By default, the Endor Labs dashboard includes data from all child namespaces. Use the **All child namespaces excluded** toggle to exclude child namespaces and view data and metrics for only the selected namespace. For more information, see [Namespaces in Endor Labs](/platform-administration/namespaces#namespaces-in-an-organization). # March 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/march-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Software Composition Analysis (SCA) for C and C++ projects Beta New You can now perform Software Composition Analysis (SCA) for C and C++ projects using Endor Labs to identify vulnerabilities, track dependencies, and ensure compliance with open-source security best practices. This helps you manage risk effectively and maintain a secure codebase. You can now include C and C++ in your [scan profile](/scan/scan-profiles/configure-scanprofile-ui) to enable scanning for C and C++ projects. For more information, see [Scan C/C++ projects](/scan/sca/c). ### Perform keyless authentication with Azure New Endor Labs now supports keyless authentication for Azure, enabling seamless and secure access without the need to store or manage keys. By configuring your Azure virtual machine with a managed identity and creating an authorization policy in Endor Labs, you can integrate with Azure services while ensuring credential security. For more information, see [Keyless authentication for Azure](/setup-deployment/ci-cd/keyless-authentication/azure-keyless-auth). ### Scan profiles Enhancement The following enhancements are available for [scan profiles](/scan/scan-profiles/build-tools). * You can configure the latest .NET SDK 9.0 toolchain in your scan profiles. This update is available for Linux and Darwin (macOS)'s arm64 and amd64 architectures, ensuring seamless integration across platforms. For more information, see [Toolchain reference](/scan/scan-profiles/build-tools). * You can set a default scan profile for a namespace. For more information, see [Set a default scan profile](/scan/scan-profiles/configure-scanprofile-ui#set-a-default-scan-profile). * You can create a standard version of a build tool and use it across all scan profiles. For more information, see [Configure build tools](/scan/scan-profiles/configure-scanprofile-ui#configure-build-tools). ### Filter findings with action policy violations Enhancement You can now filter findings that violate action policy with the action policy enforcement attribute. For more information, see [Search for findings with basic filters](/inventory-insights/findings#search-for-findings-using-basic-filters). ### Comments in Jira tickets Enhancement With Jira integration, scan findings are now automatically updated in your Jira ticket comments. If new issues are detected or existing findings are resolved, a comment is generated with details. For more information, see [Comments in Jira tickets.](/integrations/jira#view-ticket-details-in-jira) ### NTLM proxy support Enhancement You can now configure NTLM proxy settings on machines that need to connect to Endor Labs when Internet access requires NTLM-authenticated proxy servers. For more information, see [Configure proxy servers](/platform-administration/proxy-server-configuration#configure-proxy-for-ntlm-authentication). ### PR remediation support for Python Enhancement Endor Labs GitHub App (Pro) now supports PR remediation for Python, alongside Java, JavaScript, and Go. Automated remediation is available for dependencies managed through `pyproject.toml` and `requirements.txt`. For more information, see [Pull requests remediation in GitHub](/risk-remediation/automated-pull-requests) ### Include or exclude archived repositories Enhancement You can now include or exclude archived repositories when configuring scans using Azure DevOps and GitLab Apps. By default, archived repositories are excluded to conserve resources. For more information, see [Deploy Azure DevOps App](/setup-deployment/scm-integrations/azure-app) and [Deploy GitLab App](/setup-deployment/scm-integrations/gitlab-app). # May 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/may-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Outpost: On-premise scheduler for monitoring scans Beta New Outpost is a new on-premise scheduler for monitoring scans that you can run in your own Kubernetes cluster. When you install and configure Outpost, monitoring scans on your source code repositories are scheduled and run on your own Kubernetes cluster inside your firewall. For more information, see [Outpost](/setup-deployment/outpost). ### Authenticate Jira Data Center with Endor Labs Enhancement You can now use **Personal Access Token (PAT)** to authenticate your Jira Data Center to Endor Labs. For more information, see [Configure Jira integration.](/integrations/jira#configure-jira-integration-on-endor-labs) ### Pipenv support for Python projects Enhancement Endor Labs now offers support for scanning Python projects that use Pipenv as their package manager by resolving dependencies from `Pipfile` and `Pipfile.lock`. For more information, see [Scan Python projects](/scan/sca/python). ### View AI usage in the application Enhancement You can now view which features in the Endor Labs application use AI services. To modify AI access settings, go to **Settings** > **AI Access** and contact support to customize access based on your organization’s needs. For more information, see [AI access](/secure-ai-coding/ai-model-discovery). ### Projects page user interface improvements Enhancement The **Projects** page now includes enhancements that make it easier to explore, sort, and filter package data. * The following new columns help you assess the overall health of your project. * **Dependency Resolution Status** - Shows the percentage of packages for which dependency resolution was successful. * **Reachability Analysis Status** - Shows the percentage of packages for which reachability analysis was successful. * Click any column header to sort projects in ascending or descending order. For more information, see [Manage projects](/inventory-insights/projects). * From **Inventory** > **Packages**, you can now filter packages by Dependency Resolution or Reachability Analysis statuses to focus on relevant results. * Sort packages by **Package** name, **Created** date, and **Last Scanned** date to quickly locate changes or specific dependencies. For more information, see [Packages](/inventory-insights/packages#filter-package-dependencies). ### Discontinue reachability analysis for Rust Breaking change Reachability analysis is no longer supported for Rust projects. However, you can continue to scan Rust projects for software composition analysis and vulnerability detection. ### View findings location in Jira tickets Enhancement You can now view the location of the findings identified by Endor Labs in your Jira tickets. For more information, see [Findings in Jira.](/best-practices/jira-with-endor-labs#track-findings-in-jira) # November 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/november-2024/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Endor Labs Integration with Microsoft Defender for Cloud New You can now set up an integration between Endor Labs and Microsoft Defender for Cloud. This integration allows you to access reachability analysis directly within the Microsoft Defender for Cloud console, enabling you to prioritize fixes based on exploitability without switching between tools. Additionally, you can view detailed attack paths that reveal where vulnerable code is running throughout the SDLC and in the cloud, providing a new way to prioritize which vulnerabilities to remediate first. For more information, see [Set up Microsoft Defender for Cloud integration with Endor Labs](/integrations/microsoft-defender-for-cloud). ### Azure DevOps App New Endor Labs now provides an Azure DevOps app that you can use to onboard your Azure Repos and continuously monitor in Endor Labs. You can seamlessly integrate your Azure project to an Endor Labs namespace. The Azure repos in the project are scanned every 24-hours, and you can initiate a rescan according to your convenience. For more information, see [Azure DevOps App](/setup-deployment/scm-integrations/azure-app). ### Analytics dashboard New Endor Labs' new **Analytics dashboard** provides a comprehensive overview of your security metrics, tracking vulnerability trends, and resolution times across projects. You can use it to quickly assess risk levels, monitor progress, and identify areas for improving your security posture. For more information, see [Analytics dashboard](/inventory-insights/dashboards/analytics) ### Function level reachability for JavaScript projects (Beta) New Endor Labs is excited to announce the function level reachability analysis for JavaScript/TypeScript projects. You can now track the exact portion of the code in a dependency that is being reused by a program. Endor Labs generates call graphs for JavaScript/TypeScript projects to help you: * Analyze the dependencies and relationships among functions in JavaScript projects. They help identify functions or methods with known vulnerabilities or potential security issues. * Examine the call graph to identify the functions that directly or indirectly call the vulnerable functions by tracing the paths of execution. * Prioritize the vulnerabilities based on their severity, threat levels, and application importance. Call graphs assist users in comprehending the potential consequences and enable them to prioritize the resolution of vulnerabilities that are more likely to result in additional exploitation. For more information, see [Scan JavaScript/TypeScript projects](/scan/sca/javascript#enable-call-graphs-beta). ### Configure package manager integrations with AWS CodeArtifact New Configure Endor Labs to integrate with AWS CodeArtifact to use private libraries to build and scan your software. You can set up an OpenID Connect provider in AWS and create roles with trust policies to allow Endor Labs access to your CodeArtifact repositories. For more information, see [Configure package manager integrations with AWS CodeArtifact](/integrations/package-managers/aws-codeartifact). ### Configure Scan profile through Endor Labs user interface Enhancement While scanning projects using the GitHub App, you can configure a scan profile and assign it to your projects directly from the Endor Labs user interface. For more information, see [Configure Scan profile](/scan/scan-profiles/configure-scanprofile-ui). ### Differentiate base image and application layer vulnerabilities Enhancement While scanning containers, you can now distinguish the base image related vulnerabilities from those in the application layer by first scanning the base image, followed by scanning any images built on top of it. For more information, see [Discover base images](/scan/containers#discover-base-images-of-containers). ### Support for Go image with Bazel Enhancement Endor Labs now supports scanning [Go image](https://github.com/bazelbuild/rules_docker/blob/master/README.md#go_image) with Bazel. For more information, see [Bazel](/scan/bazel#supported-bazel-rules-and-features). ### Include resolved status for Jira integration Enhancement Enhanced the **RESOLVED STATUS** configuration for Jira integrations. You can now specify a custom resolved status such as **Completed** for updating Jira tickets after findings are resolved. If no status is provided, Endor Labs will default to `Done`, `Resolved`, `Closed`, or `Fixed` based on the project settings. For more information, see [Configure Jira integration](/integrations/jira#configure-jira-integration-on-endor-labs). ### Dependency detection for GitHub Action packages Enhancement Endor Labs no longer detects test dependencies in GitHub Action packages. This update reduces the number of transitive dependencies detected for GitHub Action packages, thereby streamlining dependency analysis and improving overall clarity. # November 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/november-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### GitLab App MR scans Beta New You can now scan merge requests using the Endor Labs GitLab App. You can also configure MR comments to receive comments on your merge requests. For more information, see [GitLab App MR scans](/setup-deployment/scm-integrations/gitlab-app/gitlab-mr-scan). ### Urgent notifications for newly detected malware Beta New You can now enable urgent notifications in Endor Labs to receive real-time alerts for newly discovered malware, allowing you to take immediate action. For more information, see [Urgent Notifications](/platform-administration/configure-system-settings#configure-urgent-notification-settings). ### Default branch detection Enhancement Endor Labs now sets the default branch detection flag for all projects to `true` by default. Endor Labs automatically detects the new default branch and sets that as the default reference for all the projects configured with the Endor Labs SCM Apps. For more information, see [Default branch detection](/setup-deployment/scm-integrations#default-branch-detection). ### Malware findings now enabled by default Enhancement Endor Labs now enables the malware finding policy by default for all tenants. You automatically receive findings for suspicious and malicious code across all projects, helping you detect and remediate security issues faster. For more information, see [OSS finding policy](/platform-administration/policies/finding-policies/oss-policies). # October 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/october-2024/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Find and evaluate AI models New You can now view AI models from Hugging Face on the Endor Labs platform. Search for AI models and review their Endor scores, including security, activity, popularity, and quality. These scores help you make informed decisions before integrating models into your organization. See [Discover AI models](/secure-ai-coding/ai-model-discovery) for more information. AI model list ### Scan Java projects without pom.xml New You can now scan Java projects that do not have a `pom.xml` file. This feature enables Endor Labs to scan a non-Maven and non-Gradle Java artifact, and provide the list of unresolved dependencies, resolved dependencies, and dependency tree. You can set the environment variables `ENDOR_JVM_USE_ARTIFACT_SCAN`,`ENDOR_JVM_USE_ARTIFACT_SCAN_CLASSPATH`, and `ENDOR_JVM_FIRST_PARTY_PACKAGE` to facilitate the scan of projects that contain such artifacts. See [Scan projects without pom.xml](/scan/sca/java#scan-projects-without-pomxml) for more information. ### Export multiple package versions in SBOM New You can now export multiple package versions in an SBOM through endorctl with the new command options `--package-version-uuids`, `--project-uuid`, and `--project-name`. This feature allows aggregating multiple package versions across one or many projects in a single SBOM file. See [Export multiple package versions in SBOM](/inventory-insights/sbom/exporting-sboms#export-sbom-through-endorctl) for more information. ### Enhanced user interface to view findings of a project Enhancement Endor Labs has a new user interface to view findings of a project. * **Findings list**: The new findings come in a tabular format with columns that include location, EPSS, tags, and more. * **Preset filters**: Preset filters help you to look for the category of findings you care about the most. For example, Prioritized Findings gives the list of critical vulnerability findings in the last 30 days that have either a reachable function or a reachable dependency, are not test dependencies, and have an available fix. * **Detailed drawers**: This side panel drawer provides detailed metadata inside the drawer that includes risk details, fix info, and call graphs when available. The new updates are designed to enhance your experience by providing: * **Modern look and feel**: A refreshed, modern design that’s cleaner and more intuitive. * **Enhanced navigation bar**: Streamlined menus to help you find what you need faster. * **Improved performance**: Faster load times and smoother transitions for a more efficient workflow with default filters pre-loaded. See [View findings associated with a project](/inventory-insights/findings) for more information. Project Findings ### Manage build tools Enhancement The following enhancements are now available for specifying project build toolchains: * **Auto detection of build tools** - You can enable auto detection of build tools for their projects based on the manifest files present in the repository. Auto detection is supported for Long Term Support (LTS) versions of Java, Python, Go, and .NET (C#) projects. See [Enable auto detection](/scan/scan-profiles/auto-detect-toolchains) for more information. * **Specify toolchains with scanprofile.yaml** - You must now specify build toolchains in the `scanprofile.yaml` file, a multi-document yaml file with a structure similar to Kubernetes configuration files. Previously, build toolchains were defined in the `profile.yaml` file. See [Build tools](/scan/scan-profiles/build-tools) for more information. ### Jira integration Enhancement When integrating Jira with Endor Labs, you can: * Specify an issue type from the custom Jira project such as Bug, Task, Epic, Story, or any other value when raising a Jira ticket. This enables efficient categorization and tracking of issues within the project. * Configure the integration to define custom fields with appropriate values, that align with your organization's workflows. For instance, you can create key-value pairs like `Source = Endor Labs` to associate specific information with each Jira ticket raised from Endor Labs. Make sure the endorctl version is v1.6.547 to use **ISSUE TYPE** and v1.6.567 or higher to use **Custom Fields**. See [Set up Jira integration with Endor Labs](/integrations/jira) for more information. ### Support for Bazel with Gazelle in vendored mode in Go projects Enhancement Endor Labs now supports scanning Go projects that use Bazel with Gazelle in vendored mode. See [Scan Go projects using Bazel with Gazelle in vendored mode](/scan/sca/golang#run-a-scan) ### Kotlin 2.0 Support Enhancement Endor Labs has extended Kotlin support to include version 2.0. With this enhancement, Endor Labs supports Kotlin projects from version 1.4 to 2.0. ### Other enhancements Enhancement * **Archived repositories** - The Endor Labs GitHub App no longer scans archived repositories by default. To include archived repositories in the scan, you can adjust the preferences during the GitHub App installation or by editing the integration settings afterward. * **Name change from SCPM to RSPM** - Endor Labs now uses RSPM (Repository Security Posture Management) as the standard terminology for all SCPM (Source Code Posture Management) policies and findings across the user interface and documentation. Previously, both RSPM and SCPM were used interchangeably. * **Removal of Dismiss Findings** - You can no longer dismiss a finding from the Findings page on the Endor Labs user interface. Instead, you can apply an exception policy if you want the finding to not trigger any action policy. See [Dismiss findings using an exception policy](/inventory-insights/findings#dismiss-findings-using-an-exception-policy). # October 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/october-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Discontinuation of CI/CD tool scan Breaking Change CI/CD tool scanning has been discontinued and is no longer available. This change does not affect the scanning of GitHub Action dependencies. ### Endor AI chat New Endor Labs now includes **Endor AI Chat**, an AI-powered assistant designed to help you understand vulnerabilities and take quicker, more informed action. You can ask natural language questions about security findings, scan results, package versions, and vulnerabilities. See [Endor AI chat](/secure-ai-coding/agentic-ui). ### Pre-computed reachability analysis New Endor Labs now supports pre-computed reachability analysis to determine vulnerability exposure in dependencies without requiring code compilation or full call graph generation. You can enable it using the pre-computed flag for quick scans and full scans. For more information, see [Pre-computed reachability analysis](/scan/sca/reachability-analysis/pre-computed-reachability). ### Search for authorization policies Enhancement You can now search for authorization policies using rule criteria, creator email addresses, and namespace assignments. For more information, see [Search authorization policies](/platform-administration/rbac/authorization-policies#search-authorization-policies). ### Filter notifications using project name Enhancement You can now filter notifications by project name to focus on notifications from specific projects and reduce noise from others. For more information, see [Notifications](/introduction/endor-labs-ui#notifications). ### Gradle support for Scala projects Enhancement Endor Labs now supports scanning Scala projects built with Gradle by resolving dependencies from `build.gradle` or `build.gradle.kts` files. For more information, see [Scan Scala projects](/scan/sca/scala). # February 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/release-1-6-137/index We are excited to introduce you to the latest version of Endor Labs and endorctl - v 1.6.137. This release includes the following new features. ### Sign up for Endor Labs' Free trial Discover the power of Endor Labs and the endorctl CLI with our brand-new 30-day free trial. Secure your open source software by prioritizing open source risk, reducing technical debt, and meeting compliance objectives like SBOMs & VEX. With Endor Labs' reachability analysis, DevSecOps teams can get to the right context faster, manage risks effectively, and accelerate product development. What's in the trial: * **Complete access**: Enjoy all the features without limitations for an entire month. * **Getting started**: Use Endor Labs' guided walkthrough to understand the main features of the application. * **Quick start**: Use the [quick start](/introduction/getting-started#quick-start) to get started with the application. * **Seamless integration**: Effortlessly integrate Endor Labs into your development workflows. ### Setup namespaces (Beta) Leverage namespaces to establish a logical and hierarchical structure for your projects, providing enhanced organization and clarity. As an administrator, you can: * **Organizational logic:** Create logical partitions based on organizational units, business units, project requirements, or teams. * **Access control:** Define hierarchy and control access to project resources within a namespace, ensuring a tailored and secure project environment. * **Policy governance:** Establish robust policy governance by defining rules of engagement within namespaces and setting different or identical guardrails across namespaces. For more information, see [Set up namespaces](/platform-administration/namespaces). ### Scan Kotlin projects (Beta) Scan your Kotlin projects to perform: * **Quick Scan:** Quickly assess software composition using `endorctl scan --quick-scan`. * **Deep Scan:** Conduct comprehensive analysis with dependency resolution, reachability analysis, and call graph generation using the `endorctl scan`. * **Maven and Gradle Integration:** Seamlessly integrate with Maven and Gradle for efficient builds and dependency resolution. * **Configuration Flexibility:** Configure Maven private registries and specify Gradle configurations with ease. * **Static Analysis:** In-depth analysis of Kotlin code for precise insights into dependency reachability. For more information, see [Endor Labs for Kotlin](/scan/sca/kotlin). ### Dependency discovery for Go projects using Bazel (Beta) Scan Go projects with Bazel integration using the `endorctl scan` command. By leveraging this command as a Bazel rule, you can analyze dependencies while using Bazel commands. * **Bazel Integration:** Scan Go projects by calling the `endorctl scan` command as a Bazel rule, ensuring smooth integration with Bazel workflows. * **Targeted Scanning:** Choose between scanning the entire repository or specific Go targets using language-specific Bazel rules. Alternatively, employ a Bazel query to scan targets based on specific criteria. * **Incremental Scans:** Execute scans with precision by focusing on recently updated targets, optimizing the scanning process for enhanced efficiency. For more information, see [Language-specific Bazel](/scan/bazel). ### Scan binary artifacts (Beta) Execute `endorctl` scans on binaries and artifacts without the complexities of accessing source code or build systems. * **Language support:** The scanning functionality extends to Java and Python packages, covering a wide spectrum of pre-built, bundled, or locally downloaded components. * **Artifact/Package specification:** Easily initiate scans by specifying the file path to their artifact or binary package, streamlining the scanning process. * **Comprehensive scan:** Scan specified packages to gain insights into resolved dependencies, transitive dependencies, and comprehensive call graphs, providing you with a holistic view of software components. For more information, see [Binaries and artifacts](/scan/containers). # March 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/release-1-6-194/index We are excited to introduce you to the latest version of Endor Labs and endorctl - v1.6.194. This release includes the following new features. ### Integrate Endor Labs with Vanta Integrate Vanta with Endor Labs to receive Endor Labs findings in Vanta, enabling organizations to manage risk by automating compliance requirements and streamlining security reviews. This enables you to view security findings in real-time and accelerate your security audit processes. For more information, see [Set up Vanta integration with Endor Labs](/integrations/vanta) ### Integrate Endor Labs with Slack Integrate Endor Labs with Slack and automatically receive policy violations as notifications in your Slack channels. If you are using Slack for team communication and notifications, this integration helps you to seamlessly integrate Endor Labs into your organization's existing workflows. For more information, see [Set up Slack integration with Endor Labs](/integrations/slack) ### View the CI/CD tools in your repository (Beta) Gain a profound understanding of your software development lifecycle environment by discovering all CI/CD tools used in your organization, business units, or teams. * **Automated tool discovery:** Endor Labs automatically identifies and discovers all CI/CD tools during the endorctl scan process, providing a hassle-free experience. * **Comprehensive mapping:** The end result is a comprehensive mapping of your CI/CD tools, categorized and correlated with the last timestamp of your scan. * **Enhanced visibility:** This feature enhances your understanding of the software development environment posture by providing an accurate picture of the CI/CD tools in use. For more information, see Discover CI/CD tools. # April 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/release-1-6-220/index We are excited to introduce you to the latest version of Endor Labs and endorctl - v1.6.220. This release includes new features and enhancements. ## New Features ### Sign artifacts (Beta) You can now use Endor Labs to sign and verify software artifacts. Enhance your software supply chain security by: * **Ensuring the authenticity of your software:** Understand the origins of your software and confirm its legitimacy. Verify this through integrity checks and cryptographic validation. Using a cryptographic signature ensures that container images and other build artifacts are genuine and crafted by the organization. This adds an extra layer of security to the software supply chain, making sure that only trusted and unaltered items are scheduled deployed and released. * **Tracking software origins:** Streamline audits, issue resolution, and ownership attribution by linking your software artifacts to their respective source code repository, version, and additional ownership details. Complete traceability ensures transparency, enabling organizations to validate the entire lifecycle of their software, from creation to deployment. For more information, see [Artifact Signing](/scan/containers/artifact-signing). ### Reachability analysis for Kotlin and Scala projects (Beta) Endor Labs is excited to announce the reachability analysis for [**Kotlin**](/scan/sca/kotlin) and [**Scala**](/scan/sca/scala) projects. You can now track the exact portion of the code in a dependency that is being reused by a program. Endor Labs generates call graphs for Kotlin and Scala projects to help you: * Analyze the dependencies and relationships among functions in Kotlin projects. They help identify functions or methods with known vulnerabilities or potential security issues. * Users can examine the call graph to identify the functions that directly or indirectly call the vulnerable functions by tracing the paths of execution. * Users can prioritize the vulnerabilities based on their severity, threat levels, and application importance. Call graphs assist users in comprehending the potential consequences and enable them to prioritize the resolution of vulnerabilities that are more likely to result in additional exploitation. ### Scan Swift and Objective-C projects (Beta) We are excited to further extend our language scanning capabilities by incorporating support for the Swift and Objective-C projects. Endor Labs resolves dependencies in your projects by analyzing the *Podfile* and *Podfile.lock* files. Users can view finding policy violations and dependency graphs. Manage your software risk and better understand the bill of materials associated with your software for Swift and Objective-C projects using CocoaPods. For more information, see [Endor Labs for Swift/Objective-C.](/scan/sca/swift-objective-c) ## Enhancements ### Scan EAR and WAR Java artifacts You can now run `endorctl` scans on the EAR and WAR package file formats which include a pom.xml configuration file. For more information, see [Scan artifacts.](/scan/containers) ### Flag name change for detecting dependency reachability For better clarity, the flag `--disable-phantom` is renamed to `--phantom-dependencies`. The corresponding environmental variable is renamed from `ENDOR_SCAN_DISABLE_PHANTOM` to `ENDOR_SCAN_PHANTOM_DEPS`. Set this flag to `true` to scan and detect dependencies used in source code but not declared in the package's manifest files. For more information, see [endorctl scan command.](/developers-api/cli/commands/scan) # November 2023 Source: https://docs.endorlabs.com/releasenotes/previous-releases/release-1-6-25/index We are excited to introduce you to the latest version of Endor Labs and endorctl - v 1.6.25. This release includes multiple new features. ## New Features ### Sign in to Endor Labs using email Users can now sign into Endor Labs using just their email address in addition to signing through enterprise SSO or using one of GitHub, GitLab, or Google accounts. To get started: 1. From the sign-in page, click **Log in with email link** and enter your email address. The link sent to your email address is valid for the next 15 minutes. 2. Check your email account and use the link to complete the sign-in process. 3. Enter a name for your tenant on the Endor Labs application and start using the application. ### Install endorctl with Homebrew Use Homebrew to efficiently install endorctl on macOS operating systems. Install endorctl from [Endor Lab's tap](https://github.com/endorlabs/homebrew-tap) with Homebrew by running the following commands. The tap is updated regularly with the latest endorctl release. ```bash theme={null} brew install endorlabs/tap/endorctl ``` ### Install endorctl with npm Use npm to efficiently install endorctl on macOS and Linux operating systems. Make sure that you have npm installed in your local environment and use the following command to install endorctl using npm. ```bash theme={null} npm install -g endorctl ``` [endorctl](https://www.npmjs.com/package/endorctl) is available as an npm package and is updated regularly with the latest endorctl release. # May 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/release-1-6-273/index We are excited to introduce you to the latest version of Endor Labs and endorctl - v1.6.273. This release includes new features and enhancements. ## New Features ### Detect GitHub Actions (Beta) Endor Labs provides comprehensive visibility into GitHub Action workflows used in your code repositories and helps you to: * Assess the authenticity and reliability of the dependencies in your CI environment. This enables you to determine potential exposure to known or headline incidents. * Ensures that the code in your CI workflows does not change without your knowledge. This reduces breaking changes and helps you manage your supply chain risks. * Detect and identify if any vulnerable or malicious software is part of your CI environment. For more information, see [View GitHub Action findings](/inventory-insights/findings). View GitHub Action findings To detect and view GitHub Action findings, run the endorctl scan with the `--ghactions` flag. For more information, see [endorctl scan command](/developers-api/cli/commands/scan). ## Enhancements ### Dashboard widgets Endor Labs introduces new widgets on the Dashboard to help you track the development hours and the cost metrics of your organization. * The newly introduced **Vulnerability Prioritization Funnel** systematically assesses and categorizes vulnerabilities based on their severity and category. By applying this funnel approach, organizations can prioritize addressing the most critical, exploitable, and actionable vulnerabilities first, maximizing their security efforts. * Visualize **Dev Hours Saved** and **Cost Saved** metrics on the dashboard to make more informed decisions, optimize resource allocation, and better manage project budgets. Dashboard For more information, see [View Dashboards](/inventory-insights/dashboards/oss-overview). ### Support for .NET Prop files (Beta) Endor Labs now provides the support to scan the following .NET Prop files. * Package references in `Directory.Build.props` or `Directory.Packages.props` files. * Package references in any `*.props` file and the prop file is imported in the `*.csproj` file. * Package references in `*.Targets` file For more information, see [Scan .NET projects](/scan/sca/dotnet) ### npm for Windows operating systems You can now use npm to install endorctl on Windows operating systems. For more information, see [Install endorctl with npm](/developers-api/cli/install-and-configure) ### Finding policies for Repository Security Posture Management The following new out-of-the-box finding policies are included in the application for repository security posture management (RSPM). | Policy | Severity | | ----------------------------------------------------------- | -------- | | Restrict the use of runner groups for public repositories | High | | Restrict runner groups to specific repositories | Medium | | Restrict the use of runner groups for public repositories | High | | Script injection detected in GitHub workflow files | High | | Organization webhooks must be configured with a secret | Medium | | Repository webhooks must be configured with a secret | Medium | | Default workflow token permission should be read only | High | | Restrict general action permissions to organization members | High | | Default member permissions should be restricted | Medium | For more information, see [RSPM Policies](/platform-administration/policies/finding-policies/managing-scm-configuration). ### endorctl commands Note the updates to the following flags used with the endorctl scan. | Flag | Environment variable | Description | Usage | | ------------------ | --------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--dependencies` | `ENDOR_SCAN_DEPENDENCIES` | Scan commits and generate findings for all dependencies. | Using this flag will generate findings for dependencies only. Previously it was generating findings for tools and dependencies. To fetch findings for both tools and dependencies, run the endorctl scan with `--tools` and `--dependencies`. | | `--github` | `ENDOR_SCAN_GITHUB` | Scans GitHub repositories and generates findings for GitHub misconfigurations. | Using this flag will generate findings for misconfigurations only. Previously it was generating findings for misconfigurations, tools, and dependencies. | | `--tools` | `ENDOR_SCAN_TOOLS` | Scans repositories and generates findings for CI/CD tools used in the source code repository. | Using this flag will generate findings for CI/CD tools only. Use it with `--github` to include GitHub app. It requires a valid GitHub token with `read:org access`. | | `--pr-incremental` | `ENDOR_SCAN_PR_INCREMENTAL` | Scan packages with dependencies that have changed compared to the baseline scan | Use it with `--pr-baseline` or `--enable-pr-comments` to perform an incremental scan by ignoring any packages that have the same dependencies as the baseline. | For more information, see [endorctl scan command](/developers-api/cli/commands/scan). ### Dependency reachability Note the following updates when you perform a deep scan for the following languages: * Python - The dependencies that are used in source code but not declared in the package's manifest files are detected by default when you perform a deep scan on Python projects. * JavaScript/TypeScript - You must include the flag `--call-graph-languages` with value `javascript,typescript` to detect dependencies that are used in the source code but not declared in the JavaScript or TypeScript package's manifest files. The flag `--phantom-dependencies` and its corresponding environment variable `ENDOR_SCAN_PHANTOM_DEPS` is deprecated from this release. # June 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/release-1-6-330/index We are excited to introduce you to the latest version of Endor Labs and endorctl - v1.6.330. This release includes new features and enhancements. ## New Features ### Endor Labs offerings Endor Labs application now comes packaged in the following new license bundles, designed to offer flexible and comprehensive solutions to meet your organization's unique needs. * **Endor Labs Supply Chain** - Endor Labs Supply Chain is a single platform for open-source dependency management, CI/CD security, and compliance, providing comprehensive tools to ensure your software supply chain's integrity and security. * **Endor Labs Open Source Core** - Endor Labs Open Source Core includes basic SCA and SBOM capabilities, offering essential tools for open-source software management and security assessment. * **Endor Labs Open Source Pro** - Endor Labs Open Source Pro includes all components of Endor Labs Open Source Core with additional features, providing an advanced suite for open-source software management. * **Endor Labs CI/CD** - Endor Labs CI/CD includes components to strengthen the security posture of source code repositories and verify the integrity of your builds, ensuring secure and reliable CI/CD pipelines. * **Endor Labs SBOM Hub** - Endor Labs SBOM Hub includes components to help manage your third-party SBOMs and generate findings, providing a centralized solution for software bill of materials management. * **Endor Labs Secrets** - Endor Labs Secrets includes components to help you detect and prevent secret leaks. For more details on Endor Labs' offerings and the features they include, see [pricing and packaging](https://www.endorlabs.com/pricing). ### Exception policies Exception policies define the conditions for applying an exception to a finding. When an exception is applied to a finding, it is tracked as an exception and action policies do not apply to it. Findings with exceptions are filtered out from Endor Labs reports by default. For example, exception policies can be used to: * Exclude a specific finding for a specific package from build breaking policies. * Exclude specific vulnerabilities that are accepted across your organization. * Mark an identified issue as a false positive. The application also comes with templates that you can use to quickly create exception policies. Each exception policy template provides parameters to help you customize the conditions under which an exception is applied. See [exception policies](/platform-administration/policies/exception-policies) ## Enhancements ### GitHub Action policies To address security and safety risks in GitHub Actions, Endor Labs has introduced the following new out-of-the-box finding policies for GitHub Actions. **Policies for evaluating configuration settings in workflow files** * Default workflow token permission should be read only * Workflows should not be allowed to create and approve pull requests * Restrict the use of runner groups for public repositories * Restrict runner groups to specific repositories * Restrict GitHub Actions to selected repositories **Policies for assessing configuration settings in workflow files** * Script injection detected in GitHub workflow file * Non OIDC cloud authentication detected in GitHub workflow file * Secrets object detected in GitHub workflow file * Untrusted code checkout detected in workflow file See [GitHub Action policies](/platform-administration/policies/finding-policies/github-action-policies). # July 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/release-1-6-372/index We are excited to introduce you to the latest version of Endor Labs and endorctl - v1.6.372. This release includes new features and enhancements. ### Scan containers (Beta) New Endor Labs introduces comprehensive container image scanning to help you identify and prioritize risks while ensuring compliance. **Key Features**: * **Operating system packages**: Detects packages installed via the container's base OS package manager. * **Programming language packages**: Identifies packages installed through language-specific package managers. * **Libraries and dependencies**: Scans for static and dynamic libraries, and runtime dependencies required by the application. In addition, Endor Labs generates an SBOM (Software Bill of Materials) that details all components, their versions, and associated metadata, providing a complete inventory of the container's contents. Container scan ### Customize notification templates Enhancement Endor Labs provides out-of-the-box notification templates with standard information for policy violation messages in GitHub PR comments, webhooks, email, and Slack notifications. You can use the default template or customize it to fit your organization’s specific requirements. Additionally, you can create your custom templates using [Go Templates](https://pkg.go.dev/text/template). For more details, see * [Customize GitHub PR comments notification templates](/setup-deployment/ci-cd/scan-with-github-actions#customize-github-pr-comments-notification-templates). * [Customize email notification templates](/integrations/email#customize-email-notification-templates). * [Customize webhook notification templates](/integrations/webhooks#customize-webhook-notification-templates). * [Customize Slack notification templates](/integrations/slack#customize-slack-notification-templates). # August 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/release-1-6-448/index We are excited to introduce you to the latest version of Endor Labs and endorctl - v1.6.448. This release includes new features and enhancements. ### Upgrades and recommendations (Beta) New Endor Labs upgrade and remediation workflows provide an end-to-end solution to help you discover, prioritize, manage, and resolve risks in your software development environment. * **Upgrade Impact Analysis**: Endor Labs identifies and recommends upgrades for your dependencies. By pinpointing the distinct actions that can resolve your vulnerabilities and mitigate the risks associated with updates, your security program can make more informed risk management decisions and triage issues more effectively. * **Endor Patches**: Endor Labs backports security fixes to your packages, allowing you to minimize the impact of software updates. By using an Endor patch, you can update the libraries with a minimal viable security patch that reduces your risk of breaking changes, bugs, or performance issues associated with an upgrade. For more information, see [Upgrades and remediation](/risk-remediation). ### Manage build tools (Beta) New Endor Labs provides you with the following options to define tools necessary for building your software while performing endorctl scans: * Specify toolchain configuration through endorctl API. * Specify toolchain configuration through profile.yaml file. * Falls back to the system default values for your toolchain specifications. Endor Labs will automatically install build tools in a sandbox to ensure you can run highly accurate scans. Build tools are not installed on your host. For more information, see [Manage build tools](/scan/scan-profiles/build-tools). ### Support for Azure pipelines and Azure Advanced Security New You can integrate endorctl inside an Azure pipeline and view the scan results in Azure Advanced Security. When you integrate endorctl in the Azure pipeline, endorctl scan runs and generates SARIF files during the pipeline run. The SARIF file is consumed by Advanced Security in your Azure repository. By configuring this integration, you can use Endor Labs seamlessly within the Azure ecosystem to enhance security and streamline workflows. For more information, see [Scan with Azure Pipelines](/setup-deployment/ci-cd/scan-with-azuredevops). ### Changes to endorctl CLI options Enhancement Endor Labs is introducing two new endorctl CLI options `--include-path` and `--exclude-path` to replace the existing `include` and `exclude` options. * Using these new options, you can specify the file paths or patterns to exclude or include from the endorctl scan using Glob style expressions which are easier to use. * You can easily scope your scans by defining inclusion or exclusion patterns. See [scoping scans](/best-practices/scoping-scans) for more details. The existing `--include` and `--exclude` options are deprecated. However, if these options are already in use, such as in a script, the updates remain backwards compatible, ensuring continued functionality. ### Changes to the default view on the Findings page Enhancement By default, Endor Labs now displays findings that meet the following criteria in the Findings page: * Critical severity vulnerabilities * Reachable vulnerabilities * Vulnerabilities with EPSS probability above 1% * Security vulnerabilities * Vulnerabilities created in the last week Previously, the Findings page displayed all findings when you opened the Findings page. You can use the basic or advanced filters to view additional findings. For more information, see [View Findings](/inventory-insights/findings). ### Container action policy templates Enhancement Endor Labs now provides action policy templates that you can use to quickly create action policies specific to container scanning. For more information, see [Action policy templates](/platform-administration/policies/action-policies/templates). ### PDM package manager support for Python projects Enhancement Endor Labs now offers support for scanning Python projects that use PDM as their package manager. For more information, see [Scan Python projects](/scan/sca/python). ### New fields to filter project dependencies Enhancement You can filter project dependencies and export additional fields for project dependencies with the following new fields: * License File * License Matched Text * License Name * License Type * License URL ### Sign up with GitHub Enhancement You can now sign up to Endor Labs with your GitHub account. ### Quickstart with Endor Labs GitHub App Enhancement Endor Labs GitHub App is now available as an option in quick start. The Endor Labs GitHub App allows you to quickly set up your GitHub repositories in Endor Labs and initiate scans. For more information, see [Quick start with GitHub App](/introduction/getting-started#quick-start-with-github-app). # October 2023 Source: https://docs.endorlabs.com/releasenotes/previous-releases/release-1-6-5/index We are excited to introduce you to the latest version of Endor Labs and endorctl - v 1.6.5. This release includes multiple enhancements. ## Enhancements ### Command line flag changes for enhanced usability Endor Labs has updated multiple flags to improve the overall usability for users. These changes are backwards compatible. All deprecated commands are hidden. #### New scan options Use the flags in combination with each other to make them more use case-specific. #### Renamed flags ### Troubleshoot build errors with DroidGPT Endor Labs integrates with third-party Artificial Intelligence (AI) tools to help you troubleshoot errors while performing software composition analysis, dependency resolution, or generating call graphs during an endorctl scan. In the event of an error, DroidGPT generates explanations and actionable advice for how to resolve the error on the given host system. These suggestions are displayed as part of the error log messages on the command line and can help you understand why build errors occurred during the scan process and how to resolve them. **Important** Recommendations generated are meant solely for informational purposes. Before implementing these suggestions, it is strongly advised to thoroughly verify and assess them to ensure their accuracy and suitability for your specific circumstances and work environments. Use the `ENDOR_SCAN_DROID_GPT` environment variable or the `--droid-gpt` flag to enable DroidGPT error logging on your system. * Enable error logging while performing a scan. ```bash theme={null} endorctl scan --droid-gpt ``` * Enable error logging while checking the system specifications required for performing a scan. ```bash theme={null} endorctl host-check --droid-gpt ``` **Example:** Here is an example of the recommendations generated by DroidGPT while scanning a Ruby repository where the manifest file is not correctly configured. ```text theme={null} *** NOTE: Use the following AI-generated advice at your own risk *** DroidGPT suggests the following as a possible remediation: 1. The error message indicates that there is a problem parsing the Gemfile, which is preventing the dependency tree from being generated. 2. Specifically, the error message states that there are no gemspecs at the specified location, which is causing Bundler to fail. 3. To fix this issue, you should check that the Gemfile is correctly configured and that all necessary gemspecs are present. 4. Additionally, you may want to try running `bundle install` to ensure that all dependencies are properly installed. 5. Please note that this advice is generated by an AI and there may be additional factors at play that are not captured in the error message. As such, there is no guarantee that these steps will resolve the issue, and you should proceed with caution. ``` # December 2023 Source: https://docs.endorlabs.com/releasenotes/previous-releases/release-1-6-92/index We are excited to introduce you to the latest version of Endor Labs and endorctl - v 1.6.92. This release includes multiple enhancements. ### JavaScript/TypeScript dependency reachability (Beta) Endor Labs provides superior JavaScript dependency reachability. Apart from analyzing manifest files, Endor Labs enumerates the import statements in your JavaScript code to match the import statements with the pre-installed packages and recursively traverses all files to create a dependency tree with the actual versions that are installed and used in the project. Endor Labs expertly resolves JavaScript dependencies to identify: * Dependencies listed in the manifest file but not used by the application * Dependencies used by the application but not listed in the manifest file * Dependencies listed in the manifest as transitive but used directly by the application * Dependencies categorized as test dependencies but used directly by the application The dependencies used in the source code but not declared in the package's manifest files are tagged as **Phantom**. Dependency reachability is in the **Beta** phase and is turned off by default. To detect phantom dependencies, run the endorctl scan with the flag `--disable-phantom=false`. ### pnpm package manager support for JavaScript/TypeScript projects (Beta) Users can now scan the JavaScript projects that have pnpm as their package manager. pnpm 3.0.0 and higher versions are supported. To scan JavaScript projects using pnpm, set the environment variable `ENDOR_PNPM_ENABLED` to `true` and then run the endorctl scan. ### Dependency discovery for Python and Java projects using Bazel Users can now scan their Java and Python projects using Bazel through the endorctl scan command. You can call the endorctl scan command as a Bazel rule and analyze the dependencies by using the Bazel commands. You can scan the entire repository or you can only scan specific Java or Python targets using language-specific Bazel rules. You can also use a Bazel query and scan all targets matching your query criteria. This helps in executing incremental scans on your repository and scans only the recently updated targets. # September 2024 Source: https://docs.endorlabs.com/releasenotes/previous-releases/september-2024/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Enhanced user interface for Global Findings New Endor Labs has a new user interface for viewing all findings. * **Findings list**: The new findings come in a tabular format with columns that include location, EPSS, tags, and more * **Preset filters**: These preset filters help you to look for the category of findings you care about the most. For example, **Prioritized Findings** gives you a List of critical vulnerability findings in the last 30 days that have either a reachable function or a reachable dependency, are not test dependencies, and have an available fix. * **Detailed drawers**: This side panel drawer provides detailed metadata inside the drawer that includes risk details, fix info, and call graphs when available. The new updates are designed to enhance your experience by providing: * **Modern look and feel**: A refreshed, modern design that’s cleaner and more intuitive. * **Enhanced navigation bar**: Streamlined menus to help you find what you need faster. * **Improved performance**: Faster load times and smoother transitions for a more efficient workflow with default filters pre-loaded. Findings IA. ### Scan Scala projects with Bazel Enhancement Users can now scan Scala projects with Bazel using `endorctl scan --use-bazel`. By leveraging this command as a Bazel rule, you can analyze dependencies while using Bazel commands. * **Bazel Integration**: Scan Scala projects by calling the endorctl scan command as a Bazel rule, ensuring smooth integration with Bazel workflows. * **Targeted Scanning**: Choose between scanning the entire repository or specific Scala targets using Bazel rules. You can also use a Bazel query to scan targets based on specific criteria. * **Incremental Scans**: Execute scans by focusing only on recently updated targets, optimizing the scanning process for enhanced efficiency. For more information, see [Scan with Bazel](/scan/bazel#supported-bazel-rules-and-features). ### Discover container base images Enhancement Endor Labs container scan automatically identifies the base image used in your container, along with its dependencies, such as software packages and libraries. This enables you to perform a comprehensive security assessment by detecting any vulnerabilities in the base image, ensuring your containers are secure. You can view and filter dependencies based on the container images. For more details, see [Discover container images](/scan/containers#discover-base-images-of-containers) Filter container findings. ### Integrate Endor Labs with Google Cloud Build Enhancement Integrate security scans into your Google Cloud Build pipelines to automatically detect vulnerabilities and issues during the development process. By performing scans within Google Cloud Build, you ensure that code changes are analyzed before deployment, strengthening the security and reliability of your cloud-native applications. For more details, see [Scan with Google Cloud Build](/setup-deployment/ci-cd/scan-with-google-cloud-build). # September 2025 Source: https://docs.endorlabs.com/releasenotes/previous-releases/september-2025/index We are excited to introduce the latest features and enhancements in Endor Labs. ### Discontinuation of CI/CD tool scanning Breaking change CI/CD tool scanning functionality is being deprecated and will be discontinued by the end of September 2025. This change does not affect the scanning of GitHub Action dependencies. ### Dedicated commands for container scans New You can now use the dedicated command `endorctl container scan` for container scanning. This replaces the older `endorctl scan --container` command. Migrate to `endorctl container scan` to ensure continued compatibility. For more information, see [Use new container scan commands](/scan/containers/container-migration). **Deprecation notice** The old `endorctl scan --container` commands and their corresponding flags (`--container`, `--container-tar`, and `--container-as-ref`) will be removed after a three-month deprecation period. ### Opengrep support for SAST and AI model detection New Endor Labs now uses [Opengrep](https://www.opengrep.dev/) to scan your code for SAST and AI model findings instead of Semgrep. Opengrep is an open-source, static analysis tool that finds bugs and vulnerabilities in the source code using pattern matching. Endor Labs automatically downloads Opengrep for you when you run a scan that needs it. You can continue using Semgrep with Endor Labs if you prefer. See [Use Semgrep with Endor Labs](/platform-administration/configure-system-settings#use-semgrep-with-endor-labs) for more information. ### Customize project scans using scan workflow New Endor Labs now supports Scan Workflow, which lets you define scan profiles as sequential steps within a single project scan. This gives you fine grained control over how scans run, allowing you to target different parts of your codebase more precisely. You can configure a scan workflow and assign it to your project either using the [Endor Labs API](/scan/scan-profiles/configure-scan-workflow-through-api) or through the [Endor Labs user interface](/scan/scan-profiles/configure-scanworkflow-through-ui). For more information see [Configure Scan Workflow in Endor Labs](/scan/scan-profiles#scan-workflow). ### Upgrade Impact Analysis for JavaScript/TypeScript New Endor Labs now supports Upgrade Impact Analysis (UIA) for JavaScript and TypeScript projects. UIA helps you understand the potential impact of upgrading dependencies by identifying breaking changes and dependency conflicts that may occur during upgrades. For more information, see [Upgrade impact analysis](/risk-remediation/upgrade-impact-analysis) and [JavaScript/TypeScript scanning](/scan/sca/javascript). ### Recently released dependencies (cooldown) New Endor Labs now offers policies that reduce supply chain risks by detecting newly released open source dependencies within a configurable cooldown period and optionally blocking their adoption to prevent issues from unverified packages and malware. * **Recently Released Dependencies finding policy**: Enable this finding policy to identify and raises findings for dependency versions that have been published within the defined cooldown period. Default cooldown period is 48 hours. * **Recently Released Dependencies (Cooldown) action policy**: Create an action policy from the template to define how to handle these findings. For more information, see [OSS finding policy](/platform-administration/policies/finding-policies/oss-policies), and [Recently released dependencies action policy](/platform-administration/policies/action-policies/templates#recently-released-dependencies-cooldown). ### Support for SAST scan on Windows Enhancement With the use of Opengrep instead of Semgrep for SAST scan, you can now run SAST scans on Windows. For more information, see [SAST scan with Endor Labs](/scan/sast). ### SwiftPM support for Swift/Objective-C projects Enhancement Endor Labs now supports scanning Swift projects that use the Swift Package Manager (SwiftPM) by resolving dependencies from the `Package.swift` file. For more information, see [Scan Swift projects](/scan/sca/swift-objective-c). ### Filter findings exported to GitHub Advanced Security Enhancement Endor Labs now supports filtering findings exported to GitHub Advanced Security through action policies. Findings are exported only from projects covered by configured action policies. For more information, see [Export findings to GitHub Advanced Security](/integrations/data-exporters/export-to-ghas#filter-findings-exported-to-github). ### Top 10 secret rules by severity Enhancement The First Party Code dashboard now features a stacked bar chart that displays the top 10 secret rules along with their corresponding findings. This enables you to identify high impact rules and prioritize remediation by severity. For more information, see [First-party code](/inventory-insights/dashboards/first-party-code). ### Enhanced SARIF output with vulnerability identifiers Enhancement Endor Labs now includes vulnerability aliases in SARIF output for SCA findings. Aliases such as CVE IDs, GHSA IDs, and other OSV identifiers help you track multiple identifiers for the same vulnerability and improve integration with security tools and workflows. ### Filter projects to view OSS overview Enhancement You can now use the search bar to filter projects by name to focus the OSS overview on specific projects. This helps organizations prioritize the most critical and exploitable vulnerabilities, enabling more targeted security efforts. For more information, see [First-party code](/inventory-insights/dashboards/first-party-code). ### Gradle package manager support Enhancement Endor Labs now supports Gradle package manager integration. You can configure private package manager repositories for Gradle through the user interface to scan dependencies from custom repositories and enhance dependency resolution. For more information, see [Gradle private package manager](/integrations/package-managers/gradle-private-package-manager). ### Filter findings using project name Enhancement You can now filter findings by project name, allowing you to target the findings of a specific project, focus on them, and eliminate noise from other projects. For more information, see [Search for findings using basic filters](/inventory-insights/findings#search-for-findings-using-basic-filters). ### Clone scan profiles Enhancement You can now clone scan profiles in your namespace. The cloned profile retains all parameters and custom settings, helping you set up new profiles faster and maintain consistent configurations across scans. For more information, see [Clone scan profile](/scan/scan-profiles/configure-scanprofile-ui#clone-scan-profile). # Automated Pull Requests Source: https://docs.endorlabs.com/risk-remediation/automated-pull-requests/index Automatically generate pull requests with dependency upgrades and security fixes. You can set up Remediation PRs in your GitHub environment if you use the [Endor Labs GitHub App (Pro)](/setup-deployment/scm-integrations/github-app) or the [Endor Labs GitHub Enterprise Server App](/setup-deployment/scm-integrations/github-app/github-enterprise-app). When Remediation PRs are set up, Endor Labs creates a PR to update the manifest files with dependency version upgrades, based on a remediation policy, to address vulnerability findings. You cannot have both the GitHub App and the GitHub App (Pro) simultaneously in your environment. When you migrate from one app to the other, select the same set of repositories as before to preserve the currently scanned projects and vulnerability findings after the migration. Your tenant must have the upgrades and remediation feature for Remediation PRs to function. ## Understanding Remediation PRs If Endor Labs identifies any fixes that address vulnerability findings according to the remediation policy in the next scan, it creates a pull request in GitHub with the details of the patch. You can merge the PR after review to fix the vulnerability findings. Endor Labs updates the PR if there is a recommendation change in [upgrade impact analysis](/risk-remediation/upgrade-impact-analysis). If there are any changes in the vulnerability findings, Endor Labs updates the PR description. If there is new patch version available, Endor Labs closes the existing PR with comments and opens a new PR. If you resolve the notification in Endor Labs, the PR is closed with a comment. Endor Labs does not further update the PR in the following scenarios, if you: * Add a commit to the PR * Close the PR * Delete the PR branch * Dismiss the notification in Endor Labs ## Set up Remediation PRs Complete the following tasks to set up automated PR. 1. Install and enable SCA scanner using either [GitHub App (Pro)](/setup-deployment/scm-integrations/github-app) or [GitHub Enterprise Server App](/setup-deployment/scm-integrations/github-app/github-enterprise-app). 2. [Create a GitHub PR for remediations notification integration.](#create-a-github-pr-for-remediations-notification-integration) 3. [Create a remediation policy with the notification integration that you created in the previous step.](/platform-administration/policies/remediation-policies) The following image shows an example of a remediation policy that targets projects with the tag `java` and automatically raises a PR when remediation is found for reachable dependencies that resolve critical and high issues with low upgrade risk. Remediation Policy 1 ## Remediation PRs support Remediation PRs are supported for Java (with Gradle or Maven), Go (version 1.18 and higher), Python, .NET, and JavaScript. #### Remediation PRs support matrix #### Limitations of Remediation PRs Currently, Remediation PRs have the following limitations: * Maven projects that use `dependencyManagement` tags and rely solely on dependency information in the parent pom file are not supported. * Gradle projects with convention files (Groovy files with `.gradle` extension with any name) are not supported. * Gradle projects with resource catalogues (version defined in `.toml` files) are not supported. * * Gradle projects that use Spring Framework plugins, such as the Spring Boot Gradle plugin, to manage dependency versions are not supported. These plugins handle versioning internally, so dependency versions are not explicitly declared in the Gradle manifest file. * Go projects that use the `replace` directive in `go.mod` are not supported. `replace` directives are commonly used for local development, debugging, or patching dependencies. * JavaScript projects using npm and Yarn workspaces are not supported. * .NET projects using `Directory.Packages.props` (central dependency management) or `packages.config`, are not supported. * Dependency names are case sensitive. * Updates to .NET dependencies with wildcard characters in their names are not supported. ## Create a GitHub PR for remediations notification integration Remediation notification integration allows Endor Labs to get a notification from GitHub regarding pull requests. The notification alerts the GitHub App to perform Remediation PRs. 1. Select **User menu** > **Integrations** from the left sidebar. 2. Under **Notifications**, click **Add** for **GitHub PR for Remediations**. 3. Click **Add Notification Integration**. Add GitHub PR for Remediation 4. Enter a name and description for this integration. 5. Select **Enable GitHub PR Notification Integration for Remediations**. 6. Optionally, select **Propagate this notification target to all child namespaces** so that the notification integration applies to all child namespaces. 7. Click **Add Notification Integration**. ## View remediation PRs in GitHub Endor Labs automatically generates pull requests in GitHub repositories for dependency upgrades and security fixes. Each PR contains version changes, vulnerability details, and compatibility analysis. To view the remediation PRs: 1. Navigate to your GitHub repository. 2. Click **Pull Requests** to view all the remediation PRs in the repository. GitHub Remediation PRs 3. Click on a PR to view it's details. * Select **Conversation** to view the version changes, security impact, fixed vulnerabilities, and potential risks, providing context to assess the upgrade. PR description * Select **Files changed** to view the changes made to the manifest files. files changed in the PR # Accessing the Endor Patch repository Source: https://docs.endorlabs.com/risk-remediation/endor-patches/access-endor-patch-repository/index Learn how to retrieve and use Endor Patches versions of dependencies using direct URLs and build tool configurations. Endor Labs provides patched versions of open source dependencies through a secure Maven repository. This guide explains how to access these patched artifacts using direct URLs and configure your build tools to automatically use Endor Patches. ## Repository Access The Endor Patch repository is accessible through the following URL. ```url theme={null} https://factory.endorlabs.com/v1/namespaces/$NAMESPACE/maven2 ``` You'll need API credentials from Endor Labs to access the repository. These credentials are used for authentication when downloading artifacts. See [Connecting to the Endor Patch Factory](/risk-remediation/endor-patches/connecting-to-the-factory) for detailed instructions on how to connect to the Endor Patch Factory and get your API credentials. ## Direct URL Access You can directly download specific artifacts from the Endor Patch repository using their Maven coordinates. The URL structure follows the standard Maven repository format. ```url theme={null} https://factory.endorlabs.com/v1/namespaces/$NAMESPACE/maven2/{groupId}/{artifactId}/{version}/{artifactId}-{version}.{extension} ``` ### Example: Downloading a JAR file Run the following command to download the Jackson Databind library with Endor Patches. ```bash theme={null} curl -L --user "$ENDOR_API_CREDENTIALS_KEY:$ENDOR_API_CREDENTIALS_SECRET" \ -O "https://factory.endorlabs.com/v1/namespaces/$NAMESPACE/maven2/com/fasterxml/jackson/core/jackson-databind/2.9.10.3-endor-latest/jackson-databind-2.9.10.3-endor-latest.jar" ``` ### Example: Downloading a POM file Run the following command to download the corresponding POM file. ```bash theme={null} curl -L --user "$ENDOR_API_CREDENTIALS_KEY:$ENDOR_API_CREDENTIALS_SECRET" \ -O "https://factory.endorlabs.com/v1/namespaces/$NAMESPACE/maven2/com/fasterxml/jackson/core/jackson-databind/2.9.10.3-endor-latest/jackson-databind-2.9.10.3-endor-latest.pom" ``` ## Build Tool Configuration ### Maven Configuration for build tools Configure Maven to use the Endor Patch repository by adding it to your `pom.xml` file. ```xml theme={null} endorlabs Endor Labs Patch Repository https://factory.endorlabs.com/v1/namespaces/$NAMESPACE/maven2 true false ``` Add authentication credentials to your Maven `settings.xml` file. ```xml theme={null} endorlabs ${env.ENDOR_API_CREDENTIALS_KEY} ${env.ENDOR_API_CREDENTIALS_SECRET} ``` ### Gradle Configuration for build tools Configure Gradle to use the Endor Patch repository in your `build.gradle` file. ```java theme={null} repositories { mavenCentral() maven { name = "Endor Labs Patch Repository" url = uri("https://factory.endorlabs.com/v1/namespaces/$NAMESPACE/maven2") credentials { username "$ENDOR_API_CREDENTIALS_KEY" password "$ENDOR_API_CREDENTIALS_SECRET" } } } ``` ## Using Endor Patches in Dependencies ### Maven Dependencies for dependencies Specify Endor Patch versions in your `pom.xml` file. ```xml expandable theme={null} com.fasterxml.jackson.core jackson-databind 2.9.10.3-endor-latest com.fasterxml.jackson.core jackson-databind 2.9.10.3-endor-2024-07-10 com.fasterxml.jackson.core jackson-databind 2.9.10.3 ``` ### Gradle Dependencies for dependencies Specify Endor Patch versions in your `build.gradle` file. ```java theme={null} dependencies { // Use the latest Endor patch for Jackson Databind implementation("com.fasterxml.jackson.core:jackson-databind:2.9.10.3-endor-latest") // Use a specific Endor patch version with date implementation("com.fasterxml.jackson.core:jackson-databind:2.9.10.3-endor-2024-07-10") // Use auto-patching (original version number) implementation("com.fasterxml.jackson.core:jackson-databind:2.9.10.3") } ``` ## Automatic Patching With auto patching enabled, you can use the original version numbers and Endor Labs will automatically provide the patched versions. Auto patching requires you to perform the following tasks: 1. Configure the Endor Patch repository as the first priority in your build tools. 2. Enable auto patching in your Endor Labs settings. See [Automatic patching](/risk-remediation/endor-patches/auto-patching) for detailed setup instructions. ## Version Naming Convention Endor Patch versions follow these naming conventions: * `{original-version}-endor-latest`: Latest available patch for the original version * `{original-version}-endor-{YYYY-MM-DD}`: Specific patch version with date stamp * `{original-version}`: Auto patching version (uses original version number without suffix) For example, if for Jackson Databind `v2.9.10.3`, the following versions are available: * `v2.9.10.3-endor-latest`: Latest patch for Jackson Databind `v2.9.10.3` * `v2.9.10.3-endor-2024-07-10`: Patch from July 10, 2024 for Jackson Databind `v2.9.10.3` * `2.9.10.3`: Auto patching version (no suffix needed) ## Repository Manager Configuration For enterprise environments, configure your repository manager to proxy the Endor Patch repository. Detailed setup instructions are available in the dedicated guides: * [Configure Sonatype Nexus Repository](/risk-remediation/endor-patches/configure-nexus-repository) - Complete setup for Nexus Repository Manager * [Configure JFrog Artifactory](/risk-remediation/endor-patches/configure-jfrog-artifactory) - Complete setup for JFrog Artifactory ### Basic Configuration Both repository managers require these basic settings: * **Repository URL**: `https://factory.endorlabs.com/v1/namespaces/$NAMESPACE/maven2` * **Authentication**: Use your Endor API credentials (key and secret) * **Repository Type**: Maven 2 * **Policy**: Release only (no snapshots) ## Verification and Testing The following sections describe how to verify that your build tool can resolve dependencies and that you can download artifacts directly. ### Verify Artifact Download Run the following command to test that you can download artifacts directly. ```bash theme={null} # Test with curl curl -I --user "$ENDOR_API_CREDENTIALS_KEY:$ENDOR_API_CREDENTIALS_SECRET" \ "https://factory.endorlabs.com/v1/namespaces/$NAMESPACE/maven2/com/fasterxml/jackson/core/jackson-databind/2.9.10.3-endor-latest/jackson-databind-2.9.10.3-endor-latest.jar" ``` ### Verify Build Integration Run the following commands to test that your build tool can resolve dependencies. * Maven ```bash theme={null} mvn dependency:resolve -Dclassifier=sources ``` * Gradle ```bash theme={null} ./gradlew dependencies ``` ## Debugging You can use the following commands to debug your build tool configuration. * Test repository connectivity ```bash theme={null} curl -v --user "$ENDOR_API_CREDENTIALS_KEY:$ENDOR_API_CREDENTIALS_SECRET" \ "https://factory.endorlabs.com/v1/namespaces/$NAMESPACE/maven2/" ``` * Check Maven repository configuration ```bash theme={null} mvn help:effective-settings ``` * Check Gradle repository configuration ```bash theme={null} ./gradlew buildEnvironment ``` ## Security Considerations Ensure you follow these security best practices: * Store API credentials securely using environment variables or secure credential storage * Rotate API keys regularly * Use repository managers in enterprise environments for better security and caching * Verify artifact checksums when downloading directly # Automatic patching with Endor Patches Source: https://docs.endorlabs.com/risk-remediation/endor-patches/auto-patching/index Learn how to minimize changes for an Endor patch. Upgrading software can be challenging for development teams. **Endor Automatic Patching** allows you to seamlessly fix security vulnerabilities during each software build, minimizing the effort required to maintain a secure codebase. By enabling automatic patching with Endor Labs for every build, you can automatically address vulnerabilities in both direct and transitive dependencies. This approach helps prevent a growing backlog of security issues. ## Enable Automatic Patching To start using Endor Lab’s automatic patching, follow these steps: 1. Configure Endor Labs Patch Factory. Set **Endor Labs Patch Factory** as the top priority package repository in your package manager or Artifactory virtual repository. For detailed instructions, refer to the following documentation: * Learn how to [connect to the Endor Labs Patch Factory](/risk-remediation/endor-patches/connecting-to-the-factory). * Learn how to [configure JFrog Artifactory](/risk-remediation/endor-patches/configure-jfrog-artifactory). * Learn how to [configure a Nexus repository](/risk-remediation/endor-patches/configure-nexus-repository). 2. Enable Auto Patching in Endor Labs. See [Endor Patches settings](/platform-administration/configure-system-settings#configure-endor-patches-settings) to activate auto patching. ### Considerations for automatic patching While automatic patching enhances security by addressing vulnerabilities, it introduces some trade-offs. #### Build reproducibility Automatically applied patches may alter the build process or the resulting binaries in unpredictable ways, potentially affecting build reproducibility. Endor Labs strives to provide the minimal necessary security patches to ensure your software remains secure without introducing significant changes. With automatic patching enabled, new patches are applied automatically as they become available, reducing manual intervention and enhancing your security posture. # Configure JFrog Artifactory to use Endor Patches Source: https://docs.endorlabs.com/risk-remediation/endor-patches/configure-jfrog-artifactory/index Learn how to configure your JFrog Artifactory setup to use Endor Patches. Configure JFrog Artifactory to ensure that the patched dependencies from Endor Labs are fetched and used correctly. The following procedures use Maven as the repository type, you can select the repository type based on your requirements. ## Create a remote repository for Endor Patching Create a remote repository to fetch artifacts from the Endor Patch repository. 1. Log in to the JFrog Platform as an administrator. 2. In the **Administration** module, select **Repositories**. 3. Select **Create a Repository** and click **Remote**. 4. Select **Maven** from the list of repository types. 5. In **Repository Key**, enter a name such as `endor-patch`. 6. Create an API Key in Endor Labs to authenticate to the Endor Patch repository with "Read-Only" permissions. See [creating an API key](/platform-administration/api-keys) for more detail. Keep these details handy. 7. In **URL**, enter the Endor Patch repository URL, `https://factory.endorlabs.com/v1/namespaces/$NAMESPACE/maven2`. Replace `$NAMESPACE` with your Endor Labs tenant name. 8. Enter your Endor Labs API Key ID as the **User Name** and your Endor Labs API Key secret as the **password** for your new remote repository. 9. Click **Test** to ensure you are able to successfully connect to the remote repository. Artifactory Remote Repository 10. Click **Advanced** and select **Priority Resolution** to ensure that the Endor patch repository is prioritized over other remote repositories. Artifactory Remote Repository Advanced 11. Click **Create Remote Repository**. ## Create a virtual repository for Endor Patching Create a virtual repository to simply access to Endor patch repositories and other remote repositories. 1. Log in to the JFrog Platform. 2. In the **Administration** module, select **Repositories**. 3. Select **Create a Repository** and click **Virtual**. 4. Select **Maven** from the list of repository types. 5. In **Repository Key**, enter a name such as `endor-patch`. 6. Add the `endor-patch` remote repository to this virtual repository along with other required remote repositories. 7. Ensure `endor-patch` repository is at the top of the list to prioritize it if you are using auto patching. See [the auto patching documentation for more details](/risk-remediation/endor-patches/auto-patching) Artifactory Virtual Repository 8. Click **Create Virtual Repository**. ## Edit an existing virtual repository Edit an existing virtual repository to access the Endor Patch repositories and other remote repositories. 1. Log in to the JFrog Platform. 2. In the **Administration** module, select **Repositories**. 3. Select the **Virtual** tab and click into the existing virtual repository you'd like to edit. 4. Under **Repositories** move the `endor-patch` remote repository to the selected repositories. 5. Ensure `endor-patch` repository is at the top of the list of selected repositories to prioritize it if you are using auto patching. See [the auto patching documentation](/risk-remediation/endor-patches/auto-patching) for more information. 6. Click **Save**. # Configure Sonatype Nexus Repository to use Endor Patches Source: https://docs.endorlabs.com/risk-remediation/endor-patches/configure-nexus-repository/index Learn how to configure your Sonatype Nexus Repository setup to use Endor Patches. Configure Sonatype Nexus Repository Manager to ensure that the patched dependencies from Endor Labs are fetched and used correctly. The following procedures use Maven as the repository type, you can select the repository type based on your requirements. ## Create a remote repository for Endor Patching Create a remote repository to fetch artifacts from the Endor Patch repository. 1. Log in to the Nexus Repository Manager. 2. Go to **Repositories** and click **Create repository**. 3. Select **maven2 (proxy)** as the recipe. 4. Enter the repository name, such as `endor-patch`. 5. In **Remote Storage**, enter the Endor Patch repository URL, typically given by Endor Labs, like `https://factory.endorlabs.com/v1/namespaces//maven2`. Replace `` with your Endor Labs tenant name. Remote Storage 6. Select **Authentication**, and enter your Endor Labs API Key ID as the **User Name** and your Endor Labs API Key secret as the **password**. 7. Click **Create repository** to save. ## Prioritize Endor patch repository in Maven group If you have a Maven group repository that combines multiple repositories, you need to prioritize the Endor patch repository. 1. Log in to the Nexus Repository Manager. 2. Select **Browse** and navigate to your Maven group repository that combines multiple repositories. 3. Edit the group repository and move the `endor-patch` repository to the top of the order in the members list. This ensures that Endor Patch is checked first before any other repository for patch dependencies. Member Repositories Edit 4. Click **Save** to save the changes. ## Set up routing rules in other repositories You can set up routing rules in repositories, other than the Endor patch repositories, to exclude Endor patch repositories. This will prevent other repositories from overriding the Endor patch dependencies. 1. Log in to the Nexus Repository Manager. 2. Select **Repository** in the **Administration** menu. 3. Select **Create Routing Rule**. 4. Enter a name such as `exclude-endor-patch`. 5. Select **Block** as the mode. 6. Enter the regular expression to block Endor Patches in **Matchers**. For example, `com/endor/patch/.*`. Routing Rules for Nexus 7. Click **Create Routing Rule** to save the rule. 8. Select **Browse** and navigate to the proxy repository that you want to edit. 9. Click Edit and select the routing rule that you created as the **Routing Rule**. 10. Click **Save**. # Connect to the Endor Labs Patch Factory Source: https://docs.endorlabs.com/risk-remediation/endor-patches/connecting-to-the-factory/index Learn how to connect to the Endor Labs Patch Factory and use an Endor patch. Endor Labs provides a secure Maven repository for patched versions of open source dependencies. This guide explains how to connect to the Endor Patch Factory and use Endor Patches in your build tools. See [Accessing the Endor Patch repository](/risk-remediation/endor-patches/access-endor-patch-repository) for detailed instructions on how to access the Endor Patch repository directly and configure your build tools to use Endor Patches. You can start using Endor Patches with the following simple steps: 1. [Create an API key](#create-an-api-key) 2. Configure your package manager to use Endor Patches * [Configure Gradle](#configure-gradle) * [Configure Maven](#configure-maven) 3. Specify the Endor Patch you want to use ## Create an API key To gain Rest API access to Endor Labs Patch Factory, you have to generate API credentials to authenticate to the repository. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **API Keys**. 3. Select **Generate API Key**. 4. Enter a name to identify the API key, such as "Endor Patch Factory". 5. Select the permissions to apply to the API Key, you'll need at least **Read Only**. 6. Select the expiration date of the API key. This may be either 30, 60, or 90 days. Using these credentials, you can configure Endor Labs your package manager or Artifact Repository proxy to authenticate to the Endor Patch Factory. ## Configure Gradle 1. Open the `build.gradle` file of the package you'd like to configure to use patches. 2. Include a repositories section in the `build.gradle` file to establish a repository connection to the Endor Labs Patch Factory. Make sure to replace `namespace` with the name of your Endor Labs namespace. 3. Include a reference to the Endor Patch version in the `build.gradle` file. The following example repository section shows how to configure Gradle to use the Endor Patch Factory. ```java theme={null} repositories { mavenCentral() maven { url "https://factory.endorlabs.com/v1/namespaces//maven2" credentials { username "$ENDOR_API_CREDENTIALS_KEY" password "$ENDOR_API_CREDENTIALS_SECRET" } } } ``` 4. Finally, include the Endor Labs patch version you'd like to use. For example, to use the latest patched version from Endor Labs add `-endor-latest` to the version of your dependency. The following example dependency section shows how to configure Gradle to use the Endor Patch Factory. ```java theme={null} dependencies { implementation("com.fasterxml.jackson.core:jackson-databind:2.9.10.3-endor-latest") } ``` ## Configure Maven 1. Open the `pom.xml` file of the package you'd like to configure to use patches. 2. If there is no `` section in the `pom.xml`, then create one. 3. Include a repositories section in the `pom.xml` file to establish a repository connection to the Endor Labs Patch Factory. Make sure to replace `` with the name of your Endor Labs namespace. ```xml theme={null} endorlabs https://factory.endorlabs.com/v1/namespaces//maven2 ``` 4. Next, open the Maven `settings.xml` file located at `$HOME/.m2/settings.xml` and add a `` section to the settings file with your Endor Labs credentials. * The `username` value must be your API key. * The `password` must be your API key secret. * The `id` value must be same as the value provided in the `pom.xml`. The following example `settings.xml` file shows how to configure Maven to use the Endor Patch Factory. ```xml theme={null} endorlabs ${env.ENDOR_API_CREDENTIALS_KEY} ${env.ENDOR_API_CREDENTIALS_SECRET} ``` 5. Finally, include the Endor Labs patch version you'd like to use in to your manifest. For example, to use the latest patched version from Endor Labs include `-endor-latest` to the version of your dependency. The following example dependency section shows how to configure Maven to use the Endor Patch Factory. ```xml theme={null} com.fasterxml.jackson.core jackson-databind 2.9.10.3-endor-latest ``` # Endor Patches Source: https://docs.endorlabs.com/risk-remediation/endor-patches/index Learn how to use Endor Patches and understand why they are beneficial. Endor Patches is a curated repository of software packages with backported vulnerability fixes for your security and convenience. Endor Labs identifies vulnerable functions and the commits that fixed each vulnerability in the open-source community. These fixes, along with necessary supporting commits, are applied to older software versions to create a minimum viable security patch for each library supported by Endor Labs. Endor Patches are a result of extensive research. In security, trust is crucial. Therefore, the patch details are fully transparent. The builds are hermetic ensuring they are consistent, reproducible, and reliable. The exact code changes, along with builds, build steps, and logs, are auditable and available for review. Customers can access Endor Patches through a hosted repository, where each software component has three types of versions. * A version associated with a specific patch date for build reproducibility. For instance: `v2.9.10.3-endor-2024-07-11`. * A version with the latest patched version of a library, incorporating all current patches. This can be used by appending `-endor-latest` to a package version. For instance: `v2.9.10.3-endor-latest`. * A version matching the upstream open-source version, allowing users to use the patched version without code changes. For instance: `v2.9.10.3`. By minimizing changes to fix known vulnerabilities and providing complete transparency, Endor Patches offer a comprehensive solution to help teams quickly address vulnerabilities, **even when a fix is challenging**. The following sections provide detailed information on how to use Endor Patches. Connect to the Endor Labs Patch Factory and use Endor Patches. Enable automatic patching to seamlessly fix security vulnerabilities. Build trust in your Endor Patches with full transparency and auditable build processes. Set up JFrog Artifactory to use Endor Patches with proper repository configuration. Configure Sonatype Nexus Repository Manager to prioritize Endor Patches. Learn how to retrieve and use Endor Patches versions using URLs and build tools. # Patch transparency Source: https://docs.endorlabs.com/risk-remediation/endor-patches/trust/index Build trust in your Endor Patches. In security, trust is crucial. Therefore, the patch details of an Endor patch are fully transparent. You can audit the exact code changes, builds, build steps, and logs. The builds are reproducible and hermetic. ## Review patch transparency information To review patches, build, test and deploy process used to create an Endor patch, use the `AssuredPackageVersion` API. The commands and logs used to test, deploy and build this package are stored for each version of a package as an attestation. ## Review attestations To see all information about the patch, build, test and deploy process for this Endor patch use the command: ```bash theme={null} endorctl api get -r AssuredPackageVersion -n oss --name="mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3" ``` ## Review security attestations To see the exact changes used for a given security patch, Endor Labs provides a security attestation which shows: 1. Fixed vulnerabilities 2. Exact code changes for each package 3. Exact commits used and if they are upstream commits or commits applied by Endor Labs directly To see a security attestation use the following command with the name of the package version you'd like to inspect. For this example we'll use `com.fasterxml.jackson.core:jackson-databind@2.9.10.3`: ```bash theme={null} endorctl api get -r AssuredPackageVersion -n oss --name="mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3" --field-mask="spec.security_attestation" ``` ## Review build attestations To see the build steps and build logs for an Endor patch, you can see that patch build attestation. To see a build attestation use the following command with the name of the package version you'd like to inspect. For this example we'll use `com.fasterxml.jackson.core:jackson-databind@2.9.10.3` ```bash theme={null} endorctl api get -r AssuredPackageVersion -n oss --name="mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3" --field-mask="spec.build_attestation" ``` ## Reviewing Test Attestations To see the test steps and test logs for an Endor patch, you can see that patch test attestation. To see a deployment attestation use the following command with the name of the package version you'd like to inspect. For this example we'll use `com.fasterxml.jackson.core:jackson-databind@2.9.10.3` ```bash theme={null} endorctl api get -r AssuredPackageVersion -n oss --name="mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3" --field-mask="spec.test_attestation" ``` ## Review deploy attestations To review the deployment steps and logs for an Endor patch, check the patch deployment attestation. To see a deployment attestation, use the following command with the name of the package version you'd like to inspect. For this example, we'll use `com.fasterxml.jackson.core:jackson-databind@2.9.10.3`. ```bash theme={null} endorctl api get -r AssuredPackageVersion -n oss --name="mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3" --field-mask="spec.deploy_attestation" ``` ## Reproducible Build To download the reproducible build of the patched artifact, with the name of the package version you'd like to inspect. For this example, we'll use `com.fasterxml.jackson.core:jackson-databind@2.9.10.3`. ```bash theme={null} endorctl api get -r AssuredPackageVersion -n oss --name="mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3" --field-mask="spec.reproducible_build_source_code_url" ``` Use the URL to download the source code to reproduce the build. You can find instructions on building the artifact in the README of the downloaded tar. You will need Bazel and Docker installed on your host. # Risk Remediation Source: https://docs.endorlabs.com/risk-remediation/index Learn how Endor Labs helps address security vulnerabilities through strategic software updates and patches. Software security teams face the challenge of managing thousands of dependencies across multiple projects, each with their own vulnerability landscape and upgrade requirements. Most vulnerabilities can be resolved through version upgrades which require careful analysis of compatibility, breaking changes, and dependency conflicts. Endor Labs provides automated upgrade analysis and remediation capabilities that transform vulnerability management from reactive issue identification to proactive, action-based risk resolution. The platform analyzes entire dependency trees to identify optimal upgrade paths and generates specific remediation recommendations using the following two key components: [**Upgrade Impact Analysis**](/risk-remediation/upgrade-impact-analysis) identifies and recommends upgrades for your dependencies. By pinpointing the distinct actions that can resolve your vulnerabilities and mitigate the risks associated with updates, your security program can make more informed risk management decisions and triage issues more effectively. [**Endor Patches**](/risk-remediation/endor-patches) provide backported security fixes to your packages, allowing you to minimize the impact of software updates. You can update the libraries with a minimally viable security patch that reduces the risks of breaking changes, bugs, or performance issues associated with an upgrade. [**Automated Pull Requests**](/risk-remediation/automated-pull-requests) automatically generate pull requests with dependency upgrades and security fixes directly in GitHub development workflows. This capability integrates remediation recommendations into existing CI/CD processes, enabling teams to review and merge security fixes through standard code review workflows. **Maximum number of remediation PRs** Endor Labs creates a maximum of 20 remediation PRs per project through the GitHub App integration. The following diagram demonstrates an example of a vulnerability prioritization process performed by security teams: Vulnerability Prioritization ## Remediation support matrix The following table describes the level of remediation support available for different languages. # Upgrade impact analysis Source: https://docs.endorlabs.com/risk-remediation/upgrade-impact-analysis/index Learn how Endor Labs helps you fix issues in your dependencies with remediation guidance. To help developers and security teams make informed decisions, Endor Labs provides a prioritized list of upgrade recommendations for each project and package. The recommendations are made after assessing the following criteria to determine the impact and complexity of an upgrade: * Vulnerabilities associated with a dependency's current version and those of its transitive dependencies. * Resolved vulnerabilities associated with a dependency's later versions and those of its transitive dependencies. * Heuristic factors that influence the probability of breaking changes. * Program analysis to directly identify breaking changes. Endor Labs provides an assessment of upgrade options for each dependency, including the potential impact and risk of each option. The following upgrade options are available after assessment: * The latest version of the software * The latest vulnerable free version * The most impactful update with moderate evidence of breaking changes * The most impactful update with low evidence of breaking changes **License** Upgrade impact analysis is available with the Endor Open Source Pro license. ## Remediation risk Endor Labs evaluates the remediation options for each recommended upgrade and assigns a remediation risk. To assign remediation risk, Endor Labs looks for [breaking changes](#breaking-changes) associated with the upgrade and conflicts between [dependency versions](#dependency-conflicts). There are three categories of remediation risk. * **High Remediation Risk**: This risk level is assigned when Endor Labs has high confidence that a breaking change will occur. * **Medium Remediation Risk**: This risk level is assigned when Endor Labs has identified a potential breaking change but has low to moderate confidence in its impact. It is also assigned in cases of major version conflicts that could be affected by the upgrade. * **Low Remediation Risk**: This risk level is assigned when there is minimal or no evidence suggesting that a breaking change will occur. The absence of evidence does **NOT** guarantee that it will not break your application. ### Breaking changes Breaking changes may necessitate refactoring your code to complete an upgrade due to newly introduced incompatibilities. A breaking change may occur due to the following criteria: * **API Changes**: When the public interface of a library changes, such as through renaming or removing functions, altering function signatures, or modifying expected input or output parameters. * **Behavioral Changes**: When the underlying behavior of a function or method changes, even if the interface remains the same. This can lead to unexpected results or introduce issues. * **Dependency Updates**: When a dependency of a dependency, that is a transitive dependency, introduces breaking changes, it can affect the higher-level dependency. * **Deprecations and Removals**: When deprecated features are finally removed or materially altered. * **Configuration Changes**: When the configuration format or options for a library change. * **Changes in Supported Platforms**: When a library drops support for certain platforms or versions of platforms, for example, an older version of Go. ### Dependency conflicts Dependency conflicts occur when different parts of a software project require different versions of the same dependency. These conflicts can cause multiple issues, such as build failures, runtime errors, or unexpected behavior. When there are major or minor version conflicts in your dependency graph, the impact can vary depending on the nature of the conflicts and the specific dependencies involved. While conflicts do not necessarily guarantee that updating will impact your application, they increase the likelihood that changes may affect it. ## View remediation recommendations To view Endor Labs remediation recommendations: 1. Select **Projects** from the left sidebar. 2. Select the project for which you want to view the remediations. 3. Select **Remediations** to view the list of remediation recommendations available for the project. ### Review recommendations Endor Labs lists the remediations available for the project based on the main branch of the project. You can filter the remediations by **Show Only Reachable** remediations, the **Remediation Risk**, and the time period. Additionally, you can export all findings to a CSV file. View dependencies with remediations The list shows the affected package, its current version, and the number of vulnerabilities fixed by the recommended upgrade. The list also indicates if [Endor Patches](/risk-remediation/endor-patches) are available for the package. Select a dependency to view all available upgrade options. View remediations and dependency upgrade recommendations Endor Labs assesses the upgrade options and identifies the optimal upgrade as the recommended choice based on the vulnerabilities fixed and the [remediation risk](#remediation-risk). You can view the remediation risk and the number of vulnerabilities resolved for each upgrade path. ### Review remediation risk Select an upgrade option to view the details of this upgrade path on the right sidebar. Upgrade overview information You can view the following information in **Overview**: * An overview of the remediation including the remediation risk, version age, latest scan information, and findings fixed. * The **Remediation Risk Drivers** with the potential conflicts and breaking changes. Remediation risk drivers also influence the breaking change confidence, which denotes how likely your project's functionalities can be negatively impacted due to the upgrade. * The **Details** of the package including the project, package, and version details. * The **Fixed Findings** with the details of the vulnerabilities fixed by this upgrade. Select **Potential Conflicts** to view the [potential conflicts](#dependency-conflicts) that may occur due to the upgrade. View upgrade's potential conflicts You can view all the major or minor version conflicts in your dependency graph if you upgrade to this version. Select **Breaking Changes** to view the [breaking changes](#breaking-changes) that may occur due to the upgrade. View breaking changes introduced by upgrade In a newer version, functions and interfaces may be removed or their behavior may have changed. You can view the list of functions or interfaces that are affected by this upgrade so that you can understand the impact of the upgrade. Click **View Details** to view the list of potential conflicts and breaking changes in a single page view. View details of dependency You can also view the remediation recommendations from **Projects** > **Findings**. See [Manage project findings](/inventory-insights/findings#view-remediations) for more information. ## Limitations of upgrade impact analysis Upgrade impact analysis has the following limitations: * Upgrade recommendations are proposed only for OSS packages. * Upgrade recommendations are based on the data available in the main branch of the project. * Upgrade impact analysis never recommends version downgrades. * Upgrade impact analysis does not propose upgrades for container dependencies, GitHub Actions dependencies, and approximate dependencies. * Upgrade recommendations for groups of direct dependencies are not supported. * Upgrade impact analysis for a dependency is at the project level and not across the tenant or a namespace. * Upgrade recommendations are suggested only for the dependencies with vulnerabilities. * Version constraints are excluded in the upgrade recommendations. # AI Models Source: https://docs.endorlabs.com/scan/ai-models/index Discover and govern AI models in your codebase. An AI model is a computational system designed to simulate human intelligence by performing tasks such as recognizing patterns, making decisions, predicting outcomes, or generating content. Many open source AI models are freely available for use, modification, and distribution. Just like dependencies, these AI models can bring operational and security risks in the organization that uses them. Gaining visibility into these risks can minimize the vulnerabilities introduced by them. ## AI model discovery Endor Labs picks the top ten thousand open source AI models available on Hugging Face and assigns Endor scores to them, so that you can make informed decisions before using them in your organization. See [AI model scores](/secure-ai-coding/ai-model-discovery) for more information. ## Search for AI models To search and evaluate AI models from Hugging Face, navigate to **Discovery** > **AI Models**. * Type in the search bar to look for AI Models and click **Search AI Models**. * Select a search result to view more details such as its security, activity, popularity, or operational risk score. * Click **Go to Hugging Face to see more** to view the AI model on Hugging Face website. ## AI model governance For configuring policies to govern AI model usage in your organization, see [AI model policies](/secure-ai-coding/ai-model-discovery/ai-model-policies). # AI context rules Source: https://docs.endorlabs.com/scan/ai-sast/ai-context/index Use AI context rules to give the AI SAST agents codebase-specific guidance to improve detection accuracy and reduce false positives. AI context rules give the AI SAST agents codebase-specific guidance to read while they analyze your code. The agents treat each rule as reference evidence and verify it against your actual code, applying what they can confirm and setting aside what they cannot. They use the rules to confirm genuine vulnerabilities with greater confidence, eliminate false positives, and account for behavior that is not evident from the source code alone. Specific claims are far more effective than general ones, so anchor every rule to a file, directory, framework, route, or function name the agents can locate. AI SAST scans then produce findings that closely reflect the actual security posture of your codebase. AI context rules fill the gap before reviewers act on findings, and complement their decisions afterward. When a reviewer marks a finding as a true positive or a false positive, that decision takes precedence over your written guidance. Each rule belongs to a namespace and applies to every project in it. You can narrow it with inclusions or exclusions. ## What makes an effective rule Include facts the agents cannot infer from the code on their own. Describe your codebase so the agents understand what they read and which attacks are realistic: * The primary languages and frameworks you use on the frontend and backend. * The entry points where untrusted input arrives, such as the package that holds your HTTP handlers. * The authentication and authorization enforcement points, such as the middleware that protects your API routes and the file it lives in. * The trust boundaries in your code, identified by file or directory. * The sinks and sanitizers specific to your project, named exactly. * The sources of secrets and configuration, such as a secrets manager loaded at boot rather than values hardcoded in source. * The deployment shape, such as a static frontend with all authorization enforced server-side. Highlight the patterns you want the agents to keep reporting so recurring risks specific to your codebase are not under-weighted. Name the pattern, where it recurs, why it is real, and what should make the agents raise it again. Explain the patterns that look dangerous but are safe so the agents stop reporting them. Name the pattern, its location, why it is benign in your codebase, and a discriminator that separates it from a real issue. A suppression without a discriminator, such as *trust this directory* or *we already reviewed this*, has no effect. For concrete examples, see [Example AI context rules](#example-ai-context-rules). ## What not to include in a rule AI context rules are reference evidence, not instructions, so the agents ignore anything that tries to override their built-in behavior. Do not include the following: * Instructions to turn off a detection category, such as telling the agents not to report SQL injection. * Instructions to ignore real secrets, such as hardcoded credentials. The agents always report them. * Demands for a finding that the code evidence does not support. * Generic security advice, such as OWASP, CWE, or phrases like *validate all input*. It says nothing about your code, so the agents ignore it. * Secrets, tokens, private keys, personal data, or verbatim source code. Reference sensitive code by its file path and symbol name instead. A rule is not a substitute for fixing code, so suppress a finding only when the code is genuinely safe. ## Automatic context from repository files During a scan, Endor Labs also builds context automatically. It reads guidance files in your repository along with prior reviewer decisions, grounds them against your code, and uses them alongside the rules you create. Reviewer feedback takes precedence over the rules you write, and the most recent decision takes precedence when reviewers disagree over time. By default, a scan reads these files when they are within the scan scope: * `CLAUDE.md`, and files under `.claude/agents/` and `.claude/rules/`. * `AGENTS.md`. * `.cursorrules`, and files under `.cursor/rules/`. * `.github/copilot-instructions.md`. * `SKILL.md` files, such as `.claude/skills//SKILL.md`. * `memory.md`. To index additional files, pass their paths with the `ai-sast-llm-config-paths` flag. See the [endorctl scan command reference](/developers-api/cli/commands/scan) for details. ## Create an AI context rule Create a rule to give the agents guidance about your code. You can enable or disable a rule at any time after you create it. To create an AI context rule: 1. Select **Policies** from the user menu. 2. Select **AI Context Rules**. 3. Select **Create AI Context**. 4. Enter the following details: * **AI Context Name**: A name that identifies the rule. * **Context**: The guidance the agents read. Describe the codebase, the conditions to look for, or background about the project. 5. Under **Scope**, select the namespace the rule applies to. By default, the rule applies to all projects in the namespace. 6. To limit the rule to specific projects, use **Inclusions**: * Click **Add more** under **Inclusions**. * Select the projects you want to include. * Click **Update**. 7. Optionally, enter the tags of the projects you want to include. 8. To exclude specific projects, use **Exclusions**: * Click **Add more** under **Exclusions**. * Select the projects you want to exclude. * Click **Update**. 9. Optionally, enter the tags of the projects you want to exclude. 10. Click **Create AI Context**. If a project matches both inclusions and exclusions, the exclusion takes precedence. Create an AI context rule ## Manage AI context rules You can edit, clone, delete, enable, or disable a rule at any time. Update or delete a rule when the code it describes moves or changes, so the agents do not work from stale guidance. Edit a rule to update its name, context, or scope. 1. Select **Policies** from the user menu. 2. Select **AI Context Rules**. 3. Click the vertical three dots next to the rule you want to edit. 4. Select **Edit**. 5. Update the AI context name, context, inclusions, or exclusions. 6. Click **Update AI Context**. Clone a rule to create a new rule with the same name, context, and scope. 1. Select **Policies** from the user menu. 2. Select **AI Context Rules**. 3. Click the vertical three dots next to the rule you want to clone and select **Clone**. 4. Update the AI context name, context, inclusions, and exclusions for the new rule. 5. Click **Create AI Context**. Delete a rule to remove it from your tenant. 1. Select **Policies** from the user menu. 2. Select **AI Context Rules**. 3. Click the vertical three dots next to the rule you want to remove and select **Delete**. ## Example AI context rules Adapt the names and paths in these examples to your own code. Authentication is handled upstream, so the agents stop flagging missing authentication in this service but keep reporting missing resource authorization. ```text theme={null} Architecture: these services sit behind an API gateway. User authentication is performed by auth-service before requests reach these handlers, and the verified identity arrives in the X-Verified-User header, but only treat that as authentication when route or middleware wiring shows it is required. Still report missing tenant, ownership, role, or scope authorization in this service: authentication upstream does not prove resource authorization here. ``` A shared library sanitizes HTML, so the agents suppress XSS findings on output that passes through it while still reporting sinks that bypass it. ```text theme={null} HTML output produced through github.com/acme/safehtml.Render or the @acme/security-html sanitizeHtml helper is sanitized by our shared security library. Do not report XSS when attacker-controlled text reaches templates only through those APIs and no later code calls an unsafe raw-HTML sink. Continue to report direct innerHTML, bypassRawHtml, template.HTML, or other sinks that skip the sanitizer. ``` Every protected endpoint must use a specific middleware, so the agents report routes registered without it and leave public routes alone. ```text theme={null} All production HTTP endpoints under /api/v1 must require the RequireSessionAuth middleware or an equivalent @RequireSessionAuth annotation. Endpoints under /healthz, /readyz, /metrics, and /static are public by design. Report protected /api/v1 endpoints registered without RequireSessionAuth, even when they call downstream services that perform business-logic checks. ``` Specific fields enforce tenant isolation, so the agents report routes that scope queries by user instead of by tenant. ```text theme={null} Tenant isolation is enforced with organization_id and customer_id. Any route that reads or writes invoices, users, projects, findings, or package metadata must constrain DB queries and service calls by the caller's organization_id or customer_id. A user_id check alone is not sufficient for cross-tenant resources. ``` Admin actions need two separate checks and some directories are out of scope, so the agents catch incomplete admin checks and suppress findings in non-production paths. ```text theme={null} Admin-only actions require BOTH the AdminSession middleware AND the security.admin scope in token claims. Report handlers that check only one of these before modifying users, roles, integrations, billing, or signing keys. Files under tools/, scripts/, testdata/, generated/, and docs/ are not deployed to production. Suppress findings there unless the vulnerable file is copied into a runtime container image or consumed by production code. ``` # AI SAST PR scans Source: https://docs.endorlabs.com/scan/ai-sast/ai-sast-pr-scans/index Run incremental AI SAST scans on pull requests to surface only the new findings introduced by the change. AI SAST PR scans run incremental security analysis on pull requests against an established baseline scan of the target branch. They analyze only the code changed by the pull request, deduplicate findings against the baseline, and surface only the net new findings that the pull request introduces. When the pull request is merged, the new findings are added to the baseline so that future PR scans compare against the latest mainline state. An average AI SAST PR scan completes within about five minutes. AI SAST PR scans run the [detection agent](/scan/ai-sast/detection-agent) on the pull request. AI SAST PR scans help you to: * Scan only the code changed by the pull request, with results in a few minutes. * Surface only net new, auto-triaged findings, and filter out false positives. * Review findings inline on the pull request through PR comments and in PR Runs. * Block risky merges or fail CI through action policies on the resulting findings. You can run AI SAST PR scans in the following ways: * [From the CLI using endorctl](#run-ai-sast-pr-scans-from-the-cli) to run a PR scan against a baseline branch from your terminal. * [From a CI pipeline](#run-ai-sast-pr-scans-from-ci) to invoke `endorctl scan` as part of a pull request job. * [Through SCM apps](#run-ai-sast-pr-scans-through-scm-apps) to trigger PR scans automatically when a pull request is opened or updated. ## How AI SAST PR scans work An AI SAST PR scan runs in three stages. AI SAST processes the full repository on the target branch and stores all detection-agent findings as the baseline. See [Establish a baseline scan](#establish-a-baseline-scan). A pull request triggers a PR scan that analyzes only the code changed by the pull request, using the full-repository context that the baseline established. Findings are fingerprinted and matched against the baseline. Issues that already exist in the baseline are filtered out, and only net new findings appear in the PR result, so reviewers see exactly what the pull request introduces. ## Establish a baseline scan The baseline is the reference point every AI SAST PR scan compares against. It defines the known security state of the target branch. Therefore, the PR scan can isolate net new findings from issues that already exist. The baseline gives the AI SAST agents the full-repository context they need to reason about the changed code. Without a baseline, every AI SAST finding on the pull request would surface as new, including pre-existing issues, and the PR result would not be reviewable. We recommend that you run the first baseline scan from the command line so the baseline is in place before the first PR scan is requested. Replace `/path/to/code` with the path to your repository and `` with your Endor Labs namespace. ```bash theme={null} endorctl scan --ai-sast --path=/path/to/code -n ``` When a pull request is merged, the net new findings from the PR scan are automatically added to the baseline. This keeps PR scans and baseline scans consistent for the next round of pull requests. ## Run AI SAST PR scans from the CLI You can run AI SAST PR scans using endorctl for GitHub and GitLab. The `--ai-sast --pr --pr-baseline=` combination runs the AI SAST detection agent on the changed code, deduplicates findings against the baseline, and records the results as a PR Run that does not affect main-branch monitoring scans and reports. Endor Labs stores PR and MR scan findings in PR Runs for three weeks, after which they are removed to accommodate new PR scans. Run the following command after you commit to a pull request or merge request. Ensure that you install and configure endorctl before running scans from the command line. ```bash theme={null} endorctl scan --ai-sast --pr --pr-baseline= --path=/path/to/code -n ``` Replace `` with the pull request's target branch, such as `main`. For the full list of pull request flags, see [Pull request (CI) flags](/developers-api/cli/commands/scan#pull-request-ci-flags) to learn more. AI SAST PR scans are always incremental and analyze only the code changed by the pull request. Do not set `--diff-scope` in PR scan commands. That flag is for [local diff scans](/scan/ai-sast#ai-sast-diff-scans). ## Run AI SAST PR scans from CI AI SAST PR scans can be run from a continuous integration pipeline by invoking `endorctl scan` with the `--ai-sast`, `--pr`, and `--pr-baseline` flags in jobs triggered by pull request or merge request events. This approach provides control over when scans run, supports posting findings as PR or MR comments, and allows policies to be enforced, such as failing builds or blocking merges. The scan profile assigned to the project determines the toolchains and environment used for the scan. For platform-specific YAML and command syntax, see: * [AI SAST PR scan in GitHub Actions](/setup-deployment/ci-cd/scan-with-github-actions#scanning-parameters) * [AI SAST MR scan in GitLab](/setup-deployment/ci-cd/scan-with-gitlab#ai-sast-mr-scan) * [AI SAST PR scan in Bitbucket Pipelines](/setup-deployment/ci-cd/scan-with-bitbucket#ai-sast-pr-scan) A baseline AI SAST scan must exist on the target branch before any PR scan can produce findings. See [Establish a baseline scan](#establish-a-baseline-scan). ## Run AI SAST PR scans through SCM apps The Endor Labs GitHub and GitLab apps can run AI SAST PR scans automatically on every pull request, without CI pipeline configuration. PR comments post the net new findings introduced by a pull request as a PR comment in GitHub and as an MR comment in GitLab, so developers see results in the SCM UI without leaving their review flow. Configure [Action policies](/platform-administration/policies/action-policies) to post PR comments. See [Pull request comments](/scan/pr-scans/pr-comments) to learn more. To configure AI SAST PR scans: 1. Install the [Endor Labs GitHub app](/setup-deployment/scm-integrations/github-app), [Endor Labs GitLab app](/setup-deployment/scm-integrations/gitlab-app/gitlab-mr-scan), [Bitbucket Cloud app](/setup-deployment/scm-integrations/bitbucket-cloud/bitbucket-cloud-pr-scans), or [Bitbucket Data Center app](/setup-deployment/scm-integrations/bitbucket-datacenter-app/bitbucket-datacenter-pr-scans). 2. Enable PR scans and PR comments during installation: [GitHub App Pro](/setup-deployment/scm-integrations/github-app#configure-pr-scans-during-github-app-pro-installation), [GitLab App](/setup-deployment/scm-integrations/gitlab-app/gitlab-mr-scan), [Bitbucket Cloud app](/setup-deployment/scm-integrations/bitbucket-cloud/bitbucket-cloud-pr-scans), or [Bitbucket Data Center app](/setup-deployment/scm-integrations/bitbucket-datacenter-app/bitbucket-datacenter-pr-scans). 3. [Create a scan profile](/scan/scan-profiles/configure-scanprofile-ui) and add `ENDOR_SCAN_AI_SAST=true` to the **Environment Variables**. 4. [Associate the scan profile with the project](/scan/scan-profiles/configure-scanprofile-ui#associate-projects-with-a-scan-profile). 5. Open or update a pull request on the configured repository to trigger an AI SAST PR scan. If the project does not yet have a baseline AI SAST scan, the platform automatically triggers one when the first PR scan is requested. The PR scan does not produce results or post PR comments until the baseline completes. The first baseline scan takes longer than subsequent scans because it must process the full repository. # AI SAST detection agent Source: https://docs.endorlabs.com/scan/ai-sast/detection-agent/index Use an AI agent to detect security vulnerabilities beyond traditional rule-based SAST and generate new findings labeled with an AI finding tag. Pattern-based SAST rules cannot express every class of vulnerability. You can run a SAST scan with an AI detection agent to identify security vulnerabilities that traditional rule-based SAST cannot express. Endor Labs' AI SAST detection agent reads your source code directly and uses a large language model (LLM) with full-repository context to find issues that pattern-based rules miss, such as multi-step logic flaws, context-dependent authorization issues, and bugs that only become exploitable when functions are composed across files. Unlike the AI SAST triage agent, the detection agent generates new findings directly and treats them as true positives. Each finding is labeled with an `AI` finding tag and includes the vulnerable code location, a data flow trace from source to sink, an attack vector with a concrete exploit payload and reproduction steps, an assessment of existing security controls, and a CWE classification with severity based on the context of your application. To improve detection results, you can add [AI context rules](/scan/ai-sast/ai-context) that give the agent codebase-specific guidance to read during the scan. To run an AI SAST detection agent scan: 1. Enable the **AI SAST - Detection** rule in [finding policies](/platform-administration/policies/finding-policies). 2. Run the following command. ```bash theme={null} endorctl scan --ai-sast --path=/path/to/code -n ``` The following AI SAST flags are registered with `MarkHidden` — they work but do not appear in `endorctl scan --help`. They are intended for AI SAST rollouts, benchmarking, and advanced use. Confirm with the SME before publishing. To view the findings generated by the AI detection agent scan, see [View AI SAST detection agent findings](#view-ai-sast-detection-agent-findings). ## Language support The AI SAST detection agent supports the following languages: * C * C++ * C# * Go * IaC YAML, such as Terraform * Java * JavaScript * Kotlin * Python * Ruby * Rust * Scala * Swift * TypeScript ### Scan AI agent skills Beyond application source code, the AI SAST detection agent analyzes AI agent skill files, such as `SKILL.md`, `AGENT.md`, and `CLAUDE.md`, for security weaknesses. The instructions and supporting scripts that a skill directs an agent to run can introduce risk on their own, so the agent treats these files as scan targets rather than configuration. The detection agent flags skill issues such as: * Unsafe shell command construction in supporting scripts. * Plaintext secret or token handling in skill instructions. * Risky external installs, such as pulling `@latest` from an untrusted source. Skill scanning produces SAST findings labeled with the `AI` finding tag, the same as findings from application code. It is distinct from skill scoring, which discovers installed skills and assigns a risk score rather than generating findings. ## AI detection process The AI detection agent uses a large language model (LLM) with full-repository context to systematically discover vulnerabilities. Scan the entire codebase and build a semantically searchable representation. The agent generates file hashes, function hashes, and embeddings to capture the intent of every function, and stores them with metadata such as callers and file locations. Maximum coverage at this stage minimizes false negatives later in the pipeline. Read deployment files such as Dockerfiles, Kubernetes manifests, and CI configurations to understand how the application is exposed and which framework mitigations exist. Skip files that cannot produce SAST findings, such as non-executable files. The agent uses these prioritization signals to focus security analysis on the functions that matter. Review the behavior of prioritized code using LLM-based reasoning with full-repository context. The agent traces reachability to confirm whether vulnerable code paths are actually called, follows source-to-sink chains across functions and files, and detects sanitizers or other stopping logic that may prevent exploitation. Emit confirmed vulnerabilities as new findings labeled with the `AI` finding tag and treated as true positives. Each finding includes an attack vector with a concrete exploit payload and reproduction steps that show how the issue could be triggered, and a suggested code-change diff that shows how to fix the vulnerable code. Map each finding to a CWE and assign a severity based on the context of the application rather than the CWE category alone. ## View AI SAST detection agent findings The AI detection agent generates new SAST findings by identifying security vulnerabilities beyond traditional rule-based detection. Findings generated by the AI detection agent are labeled with an `AI` finding tag, the CWE associated with the vulnerability, and a CVSS-style severity computed from the application context. To view AI SAST detection agent findings: 1. Select **Findings** > **SAST** from the left sidebar. 2. Use the **Attributes** filter and select **Yes** under the **AI SAST** filter to view findings generated by the AI detection agent. 3. Select a finding. 4. Select **Info** to view the agent's analysis and supporting evidence for the finding. * **First Introduced**: When the finding was first introduced. * **Project**: The project in which the finding was generated. * **Summary**: An agent-generated title and an explanation of the vulnerability, including the affected function, the untrusted input it consumes, and the potential impact. * **Code**: The vulnerable code location, with the file path, line numbers, and the relevant code snippet. * **Data Flow**: A trace of the issue across the code locations involved. Each stage is labeled by its role and shows the location, a short description, and the relevant code snippet. A finding can have more than one stage of the same role. * **Source**: Where untrusted input enters the application. * **Propagation**: How the input is passed or transformed as it moves toward the sink. * **Sink**: Where the input reaches the vulnerable operation. * **Security Controls**: The controls relevant to the finding, each with a status of present, missing, weak, or unknown and a short rationale. The specific controls depend on the vulnerability, such as input validation, sanitization, secrets management, or access control. * **Verification Scorecard**: Each criterion the agent verified, the evidence drawn from the code, and the resulting verdict such as confirmed, refuted, or not applicable. * **Classification**: The agent's final classification of the finding, such as `TRUE_POSITIVE`. * **Score Metrics**: The factors behind the severity score, each with an assigned value and a rationale. The scoring factors are: * **Attack Vector**: How the vulnerability is reached, such as over the network, on an adjacent network, locally on the host, or with physical access. * **Attack Complexity**: How much effort or favorable conditions an attacker needs to successfully exploit the vulnerability. * **Privileges Required**: The level of access an attacker must already have before they can exploit the vulnerability. * **User Interaction**: Whether a separate user must take an action, such as clicking a link, for the exploit to succeed. * **Confidentiality**: The impact on the secrecy of data if the vulnerability is exploited. * **Integrity**: The impact on the trustworthiness and correctness of data or system state if the vulnerability is exploited. * **Availability**: The impact on the availability of the affected system or service if the vulnerability is exploited. The scoring ends with the final **Severity** level, such as High, and its numeric score. * **Metadata**: Classification details such as the CWE ID, affected languages, and SAST tags applied to the finding. AI SAST detection agent finding For findings with high or critical severity, the agent also provides an exploit reproduction and remediation guidance. If a scan runs with the `--disable-code-snippet-storage` flag, the agent does not generate exploit reproduction or remediation. 5. Select **Exploit** to view the exploit reproduction. * **Exploit Path**: The chain of code locations an attacker traverses from the entry point through propagation to the vulnerable sink. * **Impact**: The security impact of the exploit, such as its effect on confidentiality, integrity, and availability. * **Steps to Reproduce**: Ordered steps that trigger the vulnerability. * **Bash Script**: A runnable script that reproduces the exploit. * **Concrete Values**: The specific raw and encoded values used to reproduce the exploit. Exploit reproduction 6. Select **Remediation** to view a short explanation of the recommended fix and a unified diff that applies it. Remediation guidance After you review a finding, you can tell the agents whether the analysis was correct. Select thumbs up or thumbs down on the finding to record your feedback. The agents use this feedback in future scans. To learn more, see [AI context rules](/scan/ai-sast/ai-context). # AI SAST scan Source: https://docs.endorlabs.com/scan/ai-sast/index Use AI SAST to triage findings and detect security vulnerabilities beyond traditional rule-based scanning. Endor Labs AI SAST uses large language model (LLM) agents to find security vulnerabilities and reduce false positives in your first-party code. The agents reason about code intent, data flow, and application context across your entire repository, not just one file at a time. Traditional rule-based SAST is fast and deterministic, but it generates a high number of false positives that drain developer time, and pattern-based rules cannot express every class of vulnerability. Endor Labs AI SAST agents address both limitations by combining full-repository code analysis with deployment-aware prioritization. They draw context from deployment files such as Dockerfiles, Kubernetes manifests, and CI configurations, so findings are ranked based on how the application is actually exposed. Each finding includes the vulnerable code location, a data flow trace from source to sink, an attack vector with a concrete exploit payload, and a CWE classification with severity based on the context of the application. Endor Labs offers two AI-powered SAST agents: * [AI SAST triage agent](/scan/ai-sast/triage-agent): Classifies rule-based SAST findings as true positives or false positives so you can focus on real issues. * [AI SAST detection agent](/scan/ai-sast/detection-agent): Finds vulnerabilities that rule-based scans miss, such as multi-step logic flaws and context-dependent authorization issues. New findings are tagged with `AI`. To improve the results of both agents, you can add [AI context rules](/scan/ai-sast/ai-context). The agents read these rules as reference evidence about your codebase. This helps them confirm genuine vulnerabilities, eliminate false positives, and account for behavior they cannot infer from the code alone. ## AI SAST scans in CI/CD You can run AI SAST scans as part of your CI/CD pipelines by adding the `--ai-sast` flag to your `endorctl scan` command in the following platforms: * [GitHub Actions](/setup-deployment/ci-cd/scan-with-github-actions#scanning-parameters) * [GitLab](/setup-deployment/ci-cd/scan-with-gitlab#sast-scans-in-gitlab) * [Jenkins](/setup-deployment/ci-cd/scan-with-jenkins#sast-scans-in-jenkins) * [Google Cloud Build](/setup-deployment/ci-cd/scan-with-google-cloud-build#sast-scans-in-google-cloud-build) * [Azure DevOps](/setup-deployment/ci-cd/scan-with-azuredevops#endor-labs-scan-parameters) * [Bitbucket Pipelines](/setup-deployment/ci-cd/scan-with-bitbucket#sast-scans-in-bitbucket-pipelines) * [Buildkite](/setup-deployment/ci-cd/scan-with-buildkite#run-sast-scans) * [CircleCI](/setup-deployment/ci-cd/scan-with-circleci#sast-scans-in-circleci) ## AI SAST scans in SCM apps The Endor Labs GitHub, GitLab, and Bitbucket apps can run AI SAST scans without any CI configuration. To configure AI SAST scans: 1. Install the Endor Labs SCM app for your source provider: * [Endor Labs GitHub App](/setup-deployment/scm-integrations/github-app) * [Endor Labs GitLab App](/setup-deployment/scm-integrations/gitlab-app) * [Endor Labs Bitbucket App for Bitbucket Cloud](/setup-deployment/scm-integrations/bitbucket-cloud) * [Endor Labs Bitbucket App for Bitbucket Data Center](/setup-deployment/scm-integrations/bitbucket-datacenter-app) 2. [Create a scan profile](/scan/scan-profiles/configure-scanprofile-ui) and add `ENDOR_SCAN_AI_SAST=true` to the **Environment Variables**. 3. [Associate the scan profile with the project](/scan/scan-profiles/configure-scanprofile-ui#associate-projects-with-a-scan-profile). ## AI SAST PR scans You can run AI SAST incrementally on pull requests to surface only the new findings introduced by the change, rather than rescanning the whole repository on every PR. AI SAST PR scans require an established baseline scan on the target branch, deduplicate findings against that baseline, and merge accepted findings back into the baseline after the pull request lands. See [AI SAST PR scans](/scan/ai-sast/ai-sast-pr-scans) for prerequisites, supported integrations, and setup steps. You can configure AI SAST PR scans through: * [endorctl](/scan/ai-sast/ai-sast-pr-scans#run-ai-sast-pr-scans-from-the-cli) * CI pipelines: * [GitHub Actions](/setup-deployment/ci-cd/scan-with-github-actions#scanning-parameters) * [GitLab](/setup-deployment/ci-cd/scan-with-gitlab#ai-sast-mr-scan) * [Bitbucket Pipelines](/setup-deployment/ci-cd/scan-with-bitbucket#ai-sast-pr-scan) * SCM apps: * [Endor Labs GitHub App](/setup-deployment/scm-integrations/github-app) * [Endor Labs GitLab App](/setup-deployment/scm-integrations/gitlab-app) * [Endor Labs Bitbucket Cloud App](/setup-deployment/scm-integrations/bitbucket-cloud) * [Endor Labs Bitbucket Data Center App](/setup-deployment/scm-integrations/bitbucket-datacenter-app) ## AI SAST diff scans A local diff scan runs the AI SAST detection agent against the diff in your working tree without using a baseline. It is intended for ad-hoc review during development. AI SAST diff scans are aimed at developers so they do not have to wait until a pull request is raised and scanned to identify issues or vulnerabilities in their code. Run them from your terminal to get fast feedback while you are still writing the change. Diff scans use Git locally and do not need an Endor Labs baseline. Diff scans are not deduplicated against any prior scan, so findings may overlap with issues that already exist on the target branch. Use diff scans for early exploration on a feature branch, and use AI SAST PR scans for the official review signal on a pull request. A diff scan supports two modes through the `--diff-scope` flag: * `--diff-scope=local`: Scan the files you have edited, added, or staged in your working tree but not yet committed. Use this for a pre-commit review. * `--diff-scope=baseline`: Scan the files that differ between your current checkout and the repository's default branch. Use this to review all changes on your feature branch before you open a PR. Diff scans are for local development. In CI pull request pipelines, do not set `--diff-scope`. [AI SAST PR scans](/scan/ai-sast/ai-sast-pr-scans) analyze only the changed code by default. When you run a security review through the Endor Labs MCP server, the MCP tools set `--diff-scope` automatically based on the review type, so you do not need to set it yourself. See [MCP Server](/setup-deployment/mcp). Diff scans print findings in your terminal. To run a test scan without uploading results, combine `--diff-scope` with `--dry-run`. The scan passes if it completes without warnings or errors and generates at least one AI SAST finding. ```bash theme={null} endorctl scan --ai-sast --diff-scope=local --dry-run --path . ``` # AI SAST triage agent Source: https://docs.endorlabs.com/scan/ai-sast/triage-agent/index Use an AI agent to automatically triage rule-based SAST findings as true positives or false positives and reduce manual review effort. Rule-based SAST scans are fast and deterministic, but they generate a high number of false positives that drain developer time. Endor Labs' AI SAST triage agent analyzes and intelligently triages SAST findings when you run a SAST scan. The AI agent leverages a large language model (LLM) to examine code context, trace data flows, and evaluate security controls. It automatically classifies each finding as either a `True Positive`, indicating a genuine security vulnerability, or a `False Positive`. This eliminates the need for manual review of every alert, allowing you to focus on addressing real security threats. AI analysis starts with the fast agent mode, but automatically falls back to deep analysis mode when a true positive is detected. This provides a balance between speed and accuracy by using detailed analysis only when needed. To improve triage accuracy, you can add [AI context rules](/scan/ai-sast/ai-context) that give the agent codebase-specific guidance to read during the scan. To run an AI SAST triage agent scan, use the following command. ```bash theme={null} endorctl scan --sast --path=/path/to/code -n --ai-sast-analysis=agent-fallback ``` To view the findings generated by this scan, see [View AI SAST triage agent findings](#view-ai-sast-triage-agent-findings). AI analysis does not process findings from test files such as unit tests and integration tests, or findings with low severity ratings. See [AI triage behavior](#ai-triage-behavior) to learn more. ## AI triage process The AI triage process uses a large language model (LLM) to systematically evaluate each finding through the following steps: Locate the exact code line where the SAST rule was triggered and examine the matching code patterns. Follow the data flow from where it enters the application to where it is used in potentially vulnerable code to determine if user-controlled input reaches vulnerable paths. Review function calls in the data flow path, including sanitizers, validators, and other security controls that may mitigate risks. Understand the purpose of functions involved in the rule match, how they are used in the application, and the application context such as web application, test file, or code example. Evaluate all gathered information including whether inputs are user-controlled or hard-coded, presence of sanitization functions, application context, and existing security controls to classify the finding as a true positive or false positive. AI triage processes only new findings and existing un-analyzed findings. If findings are not analyzed in the scan, they will be taken up in the next one. The triage process runs for up to 5 minutes by default. To modify the analysis timeout duration, use the `--ai-sast-analysis-timeout` flag: ```bash theme={null} endorctl scan --sast --path=/path/to/code -n --ai-sast-analysis-timeout=10m ``` ## AI triage behavior Control which findings are analyzed by AI triage and manage re-analysis behavior. By default, AI triage analyzes only new findings and previously un-analyzed findings, skipping any that have already been triaged. When running AI SAST triage agent scans, use the `--ai-sast-rescan` option to remove all existing AI analyses and re-analyze every finding from scratch. ```bash theme={null} endorctl scan --sast --path=/path/to/code -n --ai-sast-analysis=agent-fallback --ai-sast-rescan ``` The following types of findings are automatically excluded from AI triage. To include them, set the corresponding environment variable to `false`: You can generate and match findings based on AI classification by configuring these criteria when creating a [finding policy](/platform-administration/policies/finding-policies/sast-policies) or an [action policy](/platform-administration/policies/action-policies/templates#sast) from a template: * AI Analysis Status: Select **True Positive** or **False Positive** to match findings by their AI analysis result. * AI SAST: Select **Yes** to match only findings generated by the AI SAST detection agent in action policies. ## AI SAST triage agent scan options The `endorctl scan --sast` command supports the following options for AI SAST triage agent scans. ## View AI SAST triage agent findings When you run a SAST scan with `--ai-sast-analysis=agent-fallback`, the AI SAST triage agent analyzes the findings to determine if they are true security issues or false positives. The agent automatically tags verified true positives with `True Positive` and false positives with `False Positive` for easy filtering. To view AI SAST triage agent findings: 1. Select **Findings** > **SAST** from the left sidebar. 2. Use the **Attributes** filter and select **True Positive** or **False Positive** to filter findings. 3. Select a finding to view the details. * **AI Analysis**: Indicates the AI agent's classification and analysis of the finding. * **Classification**: Specifies if the finding is categorized as a true positive or false positive, including the associated confidence level. * **Analysis Summary**: A brief explanation of the security issue identified, including why the finding was triggered and what type of vulnerability it represents. * **Security Impact**: The risk level and potential consequences if the vulnerability is exploited. * **Technical Details**: Technical explanation of how the vulnerability can be exploited, including the source and sink points in the code. * **Data Flow Analysis**: Traces how untrusted data flows through your code from input to the vulnerable point. * **Security Controls**: Displays what security protections exist or are missing in the code. * **Risk Assessment**: Detailed reasoning for why the finding is classified as a true positive or false positive, with supporting evidence. * **AI Remediation**: Suggested code fix to address the vulnerability. * **Info, Rule, Explanation, and Metadata**: Displays the underlying SAST rule information, detailed explanations of the security issue, remediation guidance, and metadata such as CWE classifications and security tags. * **Info**: Contains key metadata for the finding, including confidence, impact, first detected time, project, and rule ID. * **Rule**: The specific SAST rule that detected the finding, including rule description and code examples. * **Explanation**: Analysis summary, security impact, and technical details about why this is a SAST finding. * **Remediation**: General remediation guidance for addressing this type of vulnerability. * **References**: Links to relevant security references such as CWE definitions. * **Metadata**: Contains classification details such as the CWE ID, affected languages, security tags applied to the finding, and detected rule version. AI SAST triage agent finding # Bazel Aspects Source: https://docs.endorlabs.com/scan/bazel/bazel-aspects/index Beta
Learn how to implement Endor Labs in monorepos using Bazel aspects In Bazel, a rule defines how a target is built. An aspect is a reusable extension that Bazel can apply to that rule and its dependencies during analysis. Refer to the [Bazel documentation](https://bazel.build/extending/aspects) for more information. Endor Labs uses aspects to perform software composition analysis on your software packages and extract dependency information in a structured and repeatable manner. Endor Labs provides built-in Bazel aspects that automatically enhance dependency resolution when scanning Bazel workspaces. You can run scans with aspects enabled so that Endor Labs can automatically discover and use the appropriate aspect rules for your project. If you have custom rules to build your software, you can create your own [custom Bazel aspects](#custom-bazel-aspects) and integrate them with Endor Labs. You can also use Endor Labs with [Bzlmod](https://bazel.build/external/migration) when you use Bazel aspects. Currently, Go, Java, JavaScript, TypeScript, Kotlin, Python, Scala, Rust, and Swift rulesets support Bzlmod. Software composition analysis with Bazel includes reachability analysis for Go, Java, Kotlin, Scala, and Python. ## Bazel aspect command reference The following table lists the Bazel aspect command reference. ## Supported open-source rulesets Endor Labs supports Bazel aspects for the following open-source rulesets: **Version support** Endor Labs automatically selects the appropriate aspect rule version based on the ruleset version detected in your workspace. ## Run endorctl with Bazel aspects Run the following command to scan the workspace using Bazel aspects. ```shell theme={null} endorctl scan --use-bazel --use-bazel-aspects ``` ### Scan Go vendored projects with Bazel aspects If your Go project uses [Bazel with Gazelle in vendored mode](https://github.com/bazelbuild/bazel-gazelle?tab=readme-ov-file#bazel-rule), vendored dependencies are stored under a `vendor/` directory and are not resolved through standard external repository mechanisms. To correctly identify these dependencies during an aspect scan, you must provide the path to your `go.mod` manifest file using the `--bazel-vendor-manifest-path` flag. When you specify this flag, endorctl reads the `go.mod` file, serializes its dependency information as JSON, and passes it to the Go aspect through the `json_go_mod` aspect parameter. The aspect uses this information to resolve vendored packages to their correct module names and versions. Run the following command to scan a Go vendored project using Bazel aspects. ```shell theme={null} endorctl scan --use-bazel --use-bazel-aspects \ --bazel-include-targets=//your-go-target \ --bazel-vendor-manifest-path=./go.mod ``` The `--bazel-vendor-manifest-path` flag is only applicable to Go targets. Without it, vendored Go dependencies may not be correctly resolved in the dependency graph. ## Aspect directory structure Aspect rules are located under the `.endorctl/aspects` directory in the workspace. For example, if your workspace is located at `~/my-workspace`, the aspect rules will be located at `~/my-workspace/.endorctl/aspects`. Place your custom aspects in the `.endorctl/aspects/custom` directory. ## How Bazel aspect scans work When Endor Labs scans a Bazel workspace with aspects enabled, it performs the following steps: 1. **Set up Aspects:** Initializes and extracts the Bazel aspects plugin to the workspace. 2. **Query the workspace:** Runs `bazel query` to get information about the rules versions used in the workspace. 3. **Query the target:** Runs `bazel query` to query the target being scanned and get information about the external dependencies used by it. 4. **Execute the aspect rule:** Runs `bazel build` to execute the aspect rule. 5. **Read the aspect output:** Reads the aspect output to get the dependency information. ## Bazel aspect output Bazel aspects output data in JSON format, which Endor Labs uses to populate the dependency graph. ## Bazel build configuration When executing aspects, Endor Labs runs `bazel build` with specific flags and configuration. ### Bazel aspect configuration flags Endor Labs creates a temporary `.bazelrc` configuration that includes: ### Bazel aspect remote execution and caching When using remote executors or remote caching, aspect-generated files may be stored remotely, making them inaccessible to endorctl for processing. To ensure all Bazel aspect outputs are available locally, endorctl automatically sets the following flags: * `--remote_download_outputs=all`: Forces all aspect outputs to be downloaded locally when using remote executors (for example, Build without Bytes). This is required because endorctl needs to read the json files generated by aspects to populate the dependency graph. * `--remote_download_toplevel_outputs=all`: Ensures top-level outputs are also downloaded locally, which is necessary for accessing aspect-generated files. For more information about these Bazel flags, refer to the [Bazel command-line reference](https://bazel.build/reference/command-line-reference). ## Custom Bazel aspects You can extend Bazel with custom rules to support proprietary toolchains, internal build workflows or enterprise-specific requirements that are not covered by Bazel's built-in rules. While powerful, these custom rules can obscure dependency information from standard analysis tools. ### Dependency information in custom aspects Endor Labs can automatically analyze dependencies for open-source rule sets. However, custom rules often define dependencies in a non-standard way, such as: * Generated targets * Internal dependency resolution logic Since Bazel considers custom rules as first-class citizens, dependency information inside them is not automatically visible unless explicitly surfaced. Without an aspect, Endor Labs cannot reliably determine: * What dependencies the rule introduces * Whether those dependencies are internal or third-party * How they relate to the rest of the build graph Custom aspects solve this by explicitly exposing dependency metadata in a format Endor Labs understands. ### Prerequisites for building custom aspects Before you can get started with developing your own aspects, ensure you have the following set up. #### Repository Access Your machine must have the relevant permissions to access the git repository regardless of where it is hosted, be it GitHub, GitLab, or self-hosted. #### Bazel Bazel should be installed in the machine you are going to build custom aspects. If you don't have it installed already, follow the [Bazel installation instructions](https://bazel.build/install). Run the following command to check your Bazel installation. ```bash theme={null} bazel version ``` #### endorctl CLI You also need the endorctl CLI available in your path. See [endorctl CLI documentation](https://docs.endorlabs.com/getting-started/quickstart/quickstart-local-system/) for more information. ### Build your custom Bazel aspects **Beta** Custom aspects support is currently in beta. The API and behavior may change in future releases as we continue to improve the framework based on feedback. The following sections provide information to help you build your custom Bazel aspects. * [Determine if a custom aspect is required](#determine-if-a-custom-aspect-is-required) * [Custom aspect directory structure](#custom-aspect-directory-structure) * [Aspect attributes](#aspect-attributes) * [Output file schema definition for custom aspects](#output-file-schema-definition-for-custom-aspects) * [Bazel custom aspect example](#bazel-custom-aspect-example) To help engineers get started, we have open-sourced an example for JavaScript rules. You can find the complete codebase in the [example repository](https://github.com/endorlabs/endor-aspects-it). #### Determine if a custom aspect is required You need a custom Bazel aspect if: * Your dependency graph flows through a custom Bazel rule kind (rule class) that Endor Labs does not support out of the box, such as `my_company_js_binary`. * The rule declares dependencies in non-standard locations, including custom attribute names, generated targets, or internal dependency resolution logic. #### Custom aspect directory structure Custom aspects must be available in the repository that you want to scan. Ensure that you organize them as shown in the following directory structure for endorctl to recognize them. Use **--bazel-aspect-package** to configure the base package (defaults to `@//.endorctl/aspects`). ```text theme={null} .endorctl/aspects/ └── custom/ # User-defined custom aspects └── {ecosystem}/ └── {rule_class}/ # Directory named after rule class └── {rule_class}.bzl # Custom aspect file ``` Use the following path pattern to create your custom aspect. ```text theme={null} {baseAspectPackage}/custom/{ecosystem}/{rule_class}/{rule_class}.bzl ``` #### Aspect attributes Your custom aspect must be named `endor_resolve_dependencies`. endorctl discovers it by looking for this symbol in a `.bzl` file at the path described above. The aspect definition must declare `attr_aspects` to tell Bazel which rule attributes to traverse (for example, `deps`, `data`, `srcs`). It must also declare the following mandatory attributes. The scan fails if any are excluded. The following attribute is language-specific and optional. #### Output file schema definition for custom aspects The output files must be JSON. Serialize your provider (for example, `EndorDependencyInfo`) to JSON with `json.encode_indent()`. The following table lists the fields Endor Labs expects. **depset requirement** The output file must be returned in a `depset` from the `endor_sca_info` output group. endorctl reads these depsets through BEP to construct the complete dependency tree. #### Bazel custom aspect example The [Endor Labs aspects example repository](https://github.com/endorlabs/endor-aspects-it/blob/main/example/javascript/js_library.bzl) provides a complete custom aspect for JavaScript rules. The example defines an `EndorDependencyInfo` provider that carries the metadata Endor Labs needs for each target: `original_label`, `purl`, `dependencies`, `internal`, `vendored`, and `hide`. After defining the provider, it defines helper functions. `_get_dependency_list()` goes through each dependency attribute, and collects labels of targets that have an `endor_sca_info` output group. `_get_dependency_files()` collects the output files from those targets. `_get_sca_information()` resolves the package name and version from the rule context, and falls back to the target label and `ref` attribute when explicit metadata is not available. The aspect implementation (`_impl`) extracts `deps`, `data`, `src`, and `srcs` from the rule attributes. It calls the helpers to build a list of dependency labels and collect transitive dependency files. It then constructs a PURL (for example, `pkg:npm/package-name@version`), populates the `EndorDependencyInfo` provider, and writes it to a JSON file using `json.encode_indent()`. Finally, it returns `OutputGroupInfo(endor_sca_info = depset([output_file] + dependency_files))`, combining the current target's output with all files from its transitive dependencies. The aspect itself is defined as `endor_resolve_dependencies` with the mandatory attributes described in [Aspect attributes](#aspect-attributes). endorctl reads the resulting depsets through the Build Event Protocol (BEP) to construct the complete dependency graph. These files must be available locally. endorctl ensures downloads when using remote execution or caching (see [Bazel aspect remote execution and caching](#bazel-aspect-remote-execution-and-caching)). # Bazel Source: https://docs.endorlabs.com/scan/bazel/index Learn how to implement Endor Labs in monorepos using Bazel Bazel is an open-source build and test tool commonly used in monorepos to quickly build software across multiple languages. You can use Endor Labs and Bazel to scan software for potential security issues and policy violations, prioritize vulnerabilities in the context of your applications, and understand relationships between software components. Endor Labs also supports Bazel aspects to augment the build dependency graphs with additional information and actions. If you use custom rules to build your software, you can create your own custom Bazel aspects and integrate them with Endor Labs. See [Bazel Aspects](/scan/bazel/bazel-aspects) for more information. Endor Labs supports [Bzlmod](https://bazel.build/external/migration) (Bazel's external dependency system). Bzlmod support requires Bazel aspects. Use the `--use-bazel-aspects` flag when scanning Bzlmod-based projects. ## Prerequisites for scanning Bazel projects Ensure that the following prerequisites are in place for a successful scan: * `WORKSPACE` file exists in your repository * `bazel` command installed and available * Bazel version `5.x.x`, `6.x.x`, `7.x.x`, `8.x.x`, or `9.x.x` * Supported target types in your project ### System specifications for deep scans of Bazel projects Before you proceed to run a deep scan, ensure that your system meets the following specification. | Project Size | Processor | Memory | | ----------------- | ----------------- | ------ | | Small projects | 4-core processor | 16 GB | | Mid-size projects | 8-core processor | 32 GB | | Large projects | 16-core processor | 64 GB | ### Build process for Bazel projects You can choose to build the targets before running the scan. Use the `bazel build` commands to do this by passing a comma-separated list of targets. For example, for targets `//:test` and `//:test2`, run `bazel build //:test,//:test2`. endorctl will automatically build targets if they are not already built. endorctl uses `bazel build //:target` and `bazel query 'deps(//:target)' --output graph` to build each target and analyze its dependency tree. ## Supported Bazel rules and features The following table lists the supported Bazel rules and Endor Labs features for each language. ## Bazel aspects support Endor Labs supports Bazel aspects for enhanced dependency resolution. Use the `--use-bazel-aspects` flag to enable aspects. See [Bazel Aspects](/scan/bazel/bazel-aspects) for more information. The following table lists the languages and rulesets that support Bazel aspects. ## Bzlmod support Endor Labs supports [Bzlmod](https://bazel.build/external/migration), Bazel's external dependency system. Bzlmod requires Bazel aspects. Use the `--use-bazel-aspects` flag when scanning Bzlmod-based projects. The following table lists the languages and rulesets that support Bzlmod. **Python and rules\_python** For Python, the minimum version in this table applies to Bzlmod. With `rules_python` 0.9.0 up to (but not including) 0.30.0, only the WORKSPACE model is supported (no Bzlmod). ## Quick target discovery for Bazel projects Use the following commands to find scannable targets in your repository. ```bash theme={null} bazel query 'kind(java_binary, //...)' ``` ```bash theme={null} bazel query 'kind(py_binary, //...)' ``` ```bash theme={null} bazel query 'kind(go_binary, //...)' ``` ```bash theme={null} bazel query 'kind(scala_binary, //...)' ``` ```bash theme={null} bazel query 'kind("kt_jvm_(library|binary)", //...)' ``` ```bash theme={null} bazel query 'kind(rust_binary, //...)' ``` ```bash theme={null} bazel query 'kind(swift_binary, //...)' ``` ```bash theme={null} bazel query 'kind(js_binary, //...)' ``` ```bash theme={null} bazel query 'kind(ts_project, //...)' ``` ```bash theme={null} bazel query 'kind(".*_binary", //...)' ``` ### Common query patterns for Bazel projects Use these common query patterns to find targets. Run the following command to find all targets in a specific package. ```bash theme={null} bazel query '//your-package:*' ``` Run the following command to find all binary targets across languages. ```bash theme={null} bazel query 'kind(".*_binary", //...)' ``` Run the following command to find targets with specific attributes. ```bash theme={null} bazel query 'attr(visibility, "//visibility:public", //...)' ``` Run the following command to find dependencies of a target. ```bash theme={null} bazel query 'deps(//your-target:name)' ``` Run the following command to find reverse dependencies of a target. ```bash theme={null} bazel query 'rdeps(//..., //your-target:name)' ``` ## Scan commands for Bazel projects The following table lists the common flags and options to scan Bazel projects. ### Target selection for Bazel scans To scan with Endor Labs, you need to specify which targets to analyze using one of two approaches: * **Specific target list**: Provide a comma-separated list of exact target labels using `--bazel-include-targets`. You can exclude exact labels with `--bazel-exclude-targets`. These flags do not accept Bazel target patterns such as `//...`, `:all`, or `:*`. * **Query-based selection**: Use the Bazel query language to select targets matching your criteria with `--bazel-targets-query`. Use this flag when you need pattern-based selection. ### Quick scan for Bazel projects Run a fast scan for software composition visibility without reachability analysis. ```bash theme={null} endorctl scan --use-bazel --bazel-include-targets=//your-target-name --quick-scan ``` ### Deep scan for Bazel projects Perform a full analysis with dependency resolution, reachability analysis, and call graphs. ```bash theme={null} endorctl scan --use-bazel --bazel-include-targets=//your-target-name ``` **Private Package Analysis** When a deep scan is performed, all private software dependencies are analyzed in full by default if they have not been previously scanned. This is a one-time operation and will slow down initial scans, but won't impact subsequent scans. ### Scan specific targets for Bazel projects You can scan specific targets in your Bazel project using the `--bazel-include-targets` flag. Run the following command to scan a single target. ```bash theme={null} endorctl scan --use-bazel --bazel-include-targets=//your-target-name ``` To scan multiple targets, provide a comma-separated list. ```bash theme={null} endorctl scan --use-bazel --bazel-include-targets=//target1,//target2,//target3 ``` ### Scan using queries for Bazel projects Use these commands to scan targets based on queries. ```bash theme={null} endorctl scan --use-bazel --bazel-targets-query='kind(java_binary, //...)' ``` ```bash theme={null} endorctl scan --use-bazel --bazel-targets-query='kind(py_binary, //...)' ``` ```bash theme={null} endorctl scan --use-bazel --bazel-targets-query='kind(go_binary, //...)' ``` ```bash theme={null} endorctl scan --use-bazel --bazel-targets-query='kind(scala_binary, //...)' ``` ```bash theme={null} endorctl scan --use-bazel --use-bazel-aspects --bazel-targets-query='kind("kt_jvm_(library|binary)", //...)' ``` ```bash theme={null} endorctl scan --use-bazel --use-bazel-aspects --bazel-targets-query='kind(rust_binary, //...)' ``` ```bash theme={null} endorctl scan --use-bazel --use-bazel-aspects --bazel-targets-query='kind(swift_binary, //...)' ``` ```bash theme={null} endorctl scan --use-bazel --use-bazel-aspects --bazel-targets-query='kind(js_binary, //...)' ``` ```bash theme={null} endorctl scan --use-bazel --use-bazel-aspects --bazel-targets-query='kind(ts_project, //...)' ``` ```bash theme={null} endorctl scan --use-bazel --bazel-targets-query='attr(visibility, "//visibility:public", //...)' ``` ### Scan Bazel projects with non-root workspace If your `WORKSPACE` file isn't at the repository root. ```bash theme={null} endorctl scan --use-bazel \ --bazel-targets-query='kind(java_binary, //...)' \ --bazel-workspace-path=./src/java ``` ### Scan Bazel projects with Go with Gazelle (Vendored Mode) For Go projects using Bazel with Gazelle in vendored mode. ```bash theme={null} endorctl scan --use-bazel \ --bazel-include-targets=//your-go-target \ --bazel-vendor-manifest-path=./go.mod ``` ### Scan Bazel projects with performance optimization For large codebases, disable private package analysis. ```bash theme={null} endorctl scan --use-bazel \ --bazel-include-targets=//your-target-name \ --disable-private-package-analysis ``` ### Language-specific information for Endor Labs scans For detailed information about scanning specific languages: * [Java](/scan/sca/java) * [Python](/scan/sca/python) * [Go](/scan/sca/golang) * [Scala](/scan/sca/scala) * [Kotlin](/scan/sca/kotlin) * [Rust](/scan/sca/rust) * [JavaScript](/scan/sca/javascript) * [Swift/Objective-C](/scan/sca/swift-objective-c) ## Results of Bazel projects scans You can save the findings of your scans to a local file or view the findings in the Endor Labs user interface. ### Save findings locally Run the following command to save the results of a quick scan to a local file. ```bash theme={null} endorctl scan --use-bazel --bazel-include-targets=//your-target-name --quick-scan -o json | tee results.json ``` Run the following command to save the results of a deep scan to a local file. ```bash theme={null} endorctl scan --use-bazel --bazel-include-targets=//your-target-name -o json | tee results.json ``` ### View findings in the Endor Labs user interface To view your scan results in the Endor Labs user interface: 1. Select **Projects** from the left sidebar. 2. Select the project you want to view and select **Findings** to view your scan results. For more information, see [Viewing findings in the Endor Labs user interface](/inventory-insights/findings). ## Troubleshooting Bazel projects scans Check the following common issues and solutions for Bazel projects scans. Check your query syntax and target types. Use `--bazel-workspace-path` flag. Pre-build targets with `bazel build`. Use `--disable-private-package-analysis` Specify `--bazel-vendor-manifest-path`. # Sign artifacts Source: https://docs.endorlabs.com/scan/containers/artifact-signing/index Learn how to use Endor Labs to sign container images and build artifacts in the CI pipeline. Endor Labs enhances software supply chain security by providing transparent mechanisms for signing and verifying software artifacts. * **Integrity of container images and build artifacts:** Using a cryptographic signature ensures that container images and other build artifacts are genuine and crafted by the organization. This adds an extra layer of security to the software supply chain, making sure that only authorized and unaltered items are scheduled for execution. * **Traces across workflows:** Beyond just verification, the framework offers thorough traceability. Users can trace the roots of container images and build artifacts, navigating through workflows and environments. Complete traceability ensures transparency, enabling organizations to validate the entire lifecycle of their software, from creation to deployment. * **Certificate validity:** Endor Labs uses a short-lived certificate with a validity period of 5 minutes to ensure that the signer signed the build artifact during this time frame. To further guarantee the signing occurred within the valid window, Endor Labs adds a timestamp alongside the certificate and signature, confirming the signing within the specified time frame. ## Sign artifacts You can sign artifacts using GitHub Actions or with endorctl. ### Sign using GitHub Action Use the Endor Labs [GitHub Actions](https://github.com/endorlabs/github-action/blob/main/README.md) to sign artifacts. 1. Set up authentication to Endor Labs. * (Recommended) If you are using GitHub Action keyless authentication, set an authorization policy in Endor Labs to allow your organization or repository to authenticate. See [Keyless Authentication](/setup-deployment/ci-cd/keyless-authentication) for more information. * Alternatively, authenticate with a GCP service account setup for keyless authentication from GitHub Actions or an Endor Labs API key added as a repository secret. 2. Checkout your code. 3. Install your build toolchain. 4. Build your code. 5. Sign your artifacts with Endor Labs. Use the GitHub Action `endorlabs/github-action/sign` to sign your artifacts. Set the following input parameters. See the following example workflows to sign an artifact. ```yaml expandable theme={null} name: Sign artifacts with Endor Labs on: [push, workflow_dispatch] jobs: ko-publish: name: Release ko artifact runs-on: ubuntu-latest permissions: id-token: write packages: write contents: read steps: - uses: actions/setup-go@v4 with: go-version: '1.20.x' - uses: actions/checkout@v3 - uses: ko-build/setup-ko@v0.6 - run: ko build - name: Login to the GitHub Container Registry uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.repository_owner }} password: ${{ secrets.GITHUB_TOKEN }} - name: Publish run: KO_DOCKER_REPO=ghcr.io/endorlabs/hello-sign ko publish --bare github.com/endorlabs/hello-sign - name: Get Image Digest to Sign run: | IMAGE_SHA=$(docker inspect ghcr.io/endorlabs/hello-sign:latest | jq -r '.[].Id') SIGNING_TARGET="ghcr.io/endorlabs/hello-sign@$IMAGE_SHA" echo ARTIFACT="$SIGNING_TARGET" >> $GITHUB_ENV - name: Sign with Endor Labs uses: endorlabs/github-action/sign@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: "example" artifact_name: ${{ env.ARTIFACT }} ``` ### Sign using endorctl Use the `endorctl` CLI to sign an artifact. Ensure you have downloaded the latest `endorctl` binary. To sign an artifact, run the following command. ```bash theme={null} endorctl artifact sign --name string --source-repository-ref string --certificate-oidc-issuer string ``` Specify the following options with the `endorctl artifact sign` command to include provenance information in your signed artifacts. ### Provenance information in signed artifacts The signed artifacts contain provenance metadata that describe the origin, history, and ownership of an artifact throughout its lifecycle. Including this information in signed artifacts enhances transparency, trustworthiness, and accountability. The signed artifacts include the following provenance information. ### Understand the signing process When you run the `endorctl artifact sign ` command, Endor Labs initiates the following processes: * **Authentication:** Initiates regular authentication and retrieves a token from the OIDC or workflow provider while using an authentication option such as `--enable-github-action-token` or API keys. * **Key Generation:** Generates a public and private key using ECDSA-256. * **Certificate Request:** Sends a certificate request to the private Certificate Authority to obtain a short-lived certificate. * **Provenance Inclusion:** Incorporates provenance information from the token (if available) or provided with the CLI, adding it as a set of extensions to the certificate using ASN.1 encoding. * **Image Signing:** Uses the private key to actively sign the image. * **Certificate Storage:** Stores the certificate containing provenance information along with the signature in the database. * **Timestamp:** Adds a timestamp of the signing event. ## View the signed artifacts To view the signed artifacts: 1. Select **Inventory** from the left sidebar. 2. Select **Artifacts**. The list shows signed artifacts with **Name**, **Created**, and **Last Updated** details. Signed artifacts on the Artifacts tab in Inventory 3. Use the search bar to find artifacts by name, description, or tags. You can use the following filters: * **Artifact Types**: Filter by artifact type, for example container image. * **Created**: Filter by artifact creation date. 4. Select an artifact to see its signed artifact digests in the list and provenance information. The list shows Artifact Digest, Reference, Created, and Last Updated for each digest. 5. Select an artifact digest to open **Artifact Digest Details** and view the metadata, signature and certificate details, build configuration, and source repository information. Artifact digest details with signature and provenance ## Verify artifacts You can verify artifacts using GitHub Actions or with endorctl. ### Verify using GitHub Action Use the Endor Labs [GitHub Actions](https://github.com/endorlabs/github-action/blob/main/README.md) to verify signed artifacts in your CI pipeline. Use the GitHub Action `endorlabs/github-action/verify` to verify your artifacts. Set the following input parameters. See the following example workflow to verify a signed artifact. ```yaml expandable theme={null} name: Verify artifacts with Endor Labs on: [push, workflow_dispatch] jobs: verify-artifact: name: Verify signed artifact runs-on: ubuntu-latest permissions: id-token: write packages: read contents: read steps: - uses: actions/checkout@v3 - name: Verify with Endor Labs uses: endorlabs/github-action/verify@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: "example" artifact_name: "ghcr.io/endorlabs/hello-sign@sha256:digest" certificate_oidc_issuer: "https://token.actions.githubusercontent.com" ``` ### Verify using endorctl To verify a signed artifact, use the following command: ```bash theme={null} endorctl artifact verify --name --certificate-oidc-issuer ``` Use the following command-line options with `endorctl artifact verify`: #### Understand the verification process When you run the `endorctl artifact verify --name --certificate-oidc-issuer string` command, Endor Labs initiates the following verification processes: * **Authentication:** Initiates regular authentication and retrieves a token from the OIDC or workflow provider while using an authentication option such as `--enable-github-action-token` or API keys. * **Signature Retrieval:** Retrieves a signature entry from the database using the artifact name. * If the entry is not found, the verification process fails. * **Certificate Authority Check:** Checks for a trusted Certificate Authority. * **Image Signature Validation:** Validates the image signature using the public key from the certificate. * **Timestamp Validation:** Validates that the timestamp in the signature entry is within the certificate's validity. * **OIDC Issuer Verification:** Checks whether the issuer provided matches the contents of the certificate. * **Provenance Verification:** Ensures that any provenance information from the CLI matches the ones in the certificate. ## Revoke the artifact signature You can revoke a signature of a signed artifact for reasons such as a precautionary measure to safeguard against security risks, to maintain compliance, or to uphold trust and integrity. To revoke a signature linked to an artifact and prevent its usage, use the following command: ```bash theme={null} endorctl artifact revoke-signature --name --source-repository-ref "ref" ``` Specify the following command-line options for `endorctl artifact revoke-signature`: Revoking the artifact signature invalidates the corresponding database entry and ensures that any attempts to verify the signature will fail. ## Best practices * While specifying the artifact name during the signing process, for the container images, adhere to the structure `registry.example.com/repository/image@sha256:digest`. * The signing process does not support tags. Ensure that you specify a SHA256 digest with the artifact you are signing to represent a cryptographic hash of the image's content. This produces a unique digest for every minor alteration in the image. # Container inventory Source: https://docs.endorlabs.com/scan/containers/container-findings/index Learn how to view, filter, and analyze container images in the Endor Labs platform. Container inventory provides a centralized view of all container images across your namespace, including shared base images and application images. It helps you track where the images are used, understand relationships between them, and identify potential risk exposure. Container findings are security vulnerabilities, compliance issues, and risk assessments identified during container scans. These findings provide detailed insights into the security posture of your containerized applications, including vulnerabilities in base images, application dependencies, and configuration issues. Understanding and analyzing these findings is crucial for maintaining secure container deployments and ensuring compliance with organizational security policies. ## View containers in your namespace To view all containers across your namespace: 1. Select **Containers** from the left sidebar. 2. You can view a list of container images. You can view the following information for each container image: * **Unique versions**: The number of distinct versions of the image that were scanned. * **Unique projects**: The number of projects that use the image. * **Classification**: The classification of the image, such as `app`, `base`, or `unclassified`. Container inventory on the CONTAINERS tab 3. Use the search bar to find specific container images by name. You can use the preset filters to limit which container images are listed. See [Filter containers](#filter-containers) for the full set of options. 4. Click a container image to expand it and view each scanned **Version** of that image. Each row shows the following information about the container image version: * **Version**: The image tag or digest for the version, such as `latest`. * **Container Reachability**: The profiling status and the reachability result for the version. * **Project**: The project associated with the version. * **Findings**: The number of vulnerabilities found in the container version. * **Last scanned**: The time when the version was last scanned. Expanded container image with version rows 5. Click on the three vertical dots to **View Layers** or **View Derived Images**. ### Filter containers Filtering containers helps you to narrow down the results to find specific container images based on your criteria. You can filter the containers by using the default filter options. * **Tags**: Filter by container image tags. * **Base Image Name**: Filter by the underlying base image name. * **Project**: Filter by the project associated with the version. * **Last Scanned**: Filter by last scanned time. By default, last 90 days is applied. * **Distribution**: Filter by the operating system distribution. * Toggle **Advanced** and search for containers using advanced filters. ### View container details overview Select a container row to view the container details overview on the right sidebar. You can view the following information about the container. * The **Overview** displays key dependency and finding counts with reachability and severity breakdowns, along with visibility, OSS usage, scopes, dependents, and version metadata. Container details overview * The **Reachability Analysis** summarizes profiling status and details such as application type, profile type, image classification, run duration, and entry point package when available. Container reachability analysis Select **View Details** to open the full version view. See [View container details for a version](#view-container-details-of-the-selected-version) for more information. ### View container details of the selected version Select a container version from the list of containers to view the details of the container version. #### View detailed findings You can view the findings associated with the container image under **Findings**. Each finding displays the reachability status of its dependency as an attribute label. To view and filter dependencies based on the container images, click **Container Layers** and select to view **All Layers**, **Base Image Layers Only**, or **Application Layers Only**. Container Findings with Container Layers options You can expand the finding to view detailed information, including a summary of the issue, when it was first introduced, and remediation guidance. You can manage the finding using the available options: * **Add Exception**: Add an exception to exclude this finding from future scans for accepted or mitigated vulnerabilities. * **More Details**: Access additional information about the vulnerability, including detailed technical descriptions and remediation steps. #### View container version overview Select **Overview** to view the summary of the selected container version. You can view the finding risk matrix and metadata such as dependencies, visibility, scopes, and package version details. Container version Overview tab #### View dependent projects Select **Dependents** to view the projects that depend on the selected container version. Each entry shows finding counts, origin of findings, project origin, last scanned time, and container reachability status. Dependents for the selected container version #### View dependencies of the selected container version Select **Dependencies** to view the dependencies of the selected container version. Each entry shows the dependency and requested version, its type, reachability status, visibility, and whether source code is available. Dependencies for the selected container version #### View dependency graph Select **Dependency Graph** to view the dependency graph of the selected container version. Dependency graph for a container version #### View container layers Select **Container Layers** to view multiple layers numbered sequentially, where each number represents the order in which Docker commands were executed. Click on a layer to view the Docker command and findings associated with that specific layer. Container layers and Dockerfile steps #### View scan history Select **Scan History** to see past scan runs for the container. This shows when the container was last scanned, previous scan results, and any changes in findings over time. You can compare different scan runs to track improvements or identify when new vulnerabilities were introduced. Scan history for a container version ## View container findings in a project To view findings from the container scan: 1. Select **Projects** from the left sidebar. 2. Select the project for which you want to view the container findings. 3. Select **Containers** from the preset filters. Project container on the Findings tab 4. To view and filter dependencies based on the container images, select **Container Layers** and choose to view **All Layers**, **Base Image Layers Only**, or **Application Layers Only**. ## View findings in your namespace To view all container findings across your namespace, go to **Findings** from the left sidebar and select **Containers** from the preset filters. This shows all container related vulnerabilities and security issues across your entire organization. You can search findings using basic filters or advanced filters to narrow down the results based on your specific criteria. Findings with the Containers preset filter # Migrate to new container scan commands Source: https://docs.endorlabs.com/scan/containers/container-migration/index Learn how to migrate from deprecated container scan flags to the new `endorctl container scan` command. With the release of the new `endorctl container scan` commands, Endor Labs will remove the old `endorctl scan` container commands and their related flags after a three-month deprecation period. Use the new dedicated command to ensure continued compatibility. ### Mapping of deprecated and new container scan commands ### Examples * To scan a basic container image: * **Old:** `endorctl scan --container nginx:latest --namespace my-namespace` * **New:** `endorctl container scan --image nginx:latest --namespace my-namespace` * To scan a container tar file: * **Old:** `endorctl scan --container-tar /path/to/image.tar --namespace my-namespace` * **New:** `endorctl container scan --image-tar /path/to/image.tar --namespace my-namespace` * To scan a container with a project name: * **Old:** `endorctl scan --container nginx:latest --project-name my-nginx --namespace my-namespace` * **New:** `endorctl container scan --image nginx:latest --project-name my-nginx --namespace my-namespace` * To scan a container in a reference context: * **Old:** `endorctl scan --container nginx:latest --container-as-ref --namespace my-namespace` * **New:** `endorctl container scan --image nginx:latest --as-ref --namespace my-namespace` # Container reachability Source: https://docs.endorlabs.com/scan/containers/container-reachability/index Determine if the packages inside a container image are actually used by your application at runtime. Endor Labs allows you to determine whether the OS packages present in a container image are actually used by your application at runtime. Use container reachability to distinguish dependencies that are merely installed from those that are actively exercised during execution, helping security teams prioritize the most critical security issues for remediation. Run the container scan using the new `endorctl container scan` command. The `endorctl scan --container` command does not support container reachability. Endor Labs supports the following two container reachability modes. Choose the mode that aligns with how your workload executes and what dependencies it requires at runtime. * **Basic Reachability**: Endor Labs executes and profiles the container image in a local environment during the scan. Select this method when the application can run without relying on external services. * [**Instrumented Reachability**](/scan/containers/instrumented-reachability): Endor Labs integrates a sensor into the container image and deploys it in the environment where the application normally runs. The sensor captures runtime behavior and produces a profiling report, which Endor Labs then analyzes. Select this method for workloads that rely on external services or interactions that you cannot trigger in a brief local execution. ## Prerequisites To perform container reachability analysis, ensure you meet the following system requirements: * The container must have sufficient CPU and memory resources to run successfully. * The container must be runnable. * The container must have network access if its startup process requires external communication. * Install Docker daemon `dockerd` on the host. It must be runnable and accessible to the current user without elevated privileges. For example, `docker images` should work without `sudo`. * The negotiated Docker API version between the client and server must be `1.48` or higher. * Run the scan on either a Linux or macOS host machine. Container reachability supports both amd64 and arm64 architectures. ## Determine container reachability Endor Labs determines container reachability by extracting OS packages from the container image, profiling the container's runtime behavior, and correlating the results to identify which dependencies are actually used during execution. The following steps describe how Endor Labs determines container reachability. 1. **Dependency extraction** - Endor Labs extracts all packages and dependencies present in the container image by analyzing its file system to identify installed OS packages and their file path locations within the image. 2. **Dynamic profiling** - Endor Labs runs the container image in a controlled environment, monitoring which OS-level files and dependencies the application accesses during execution. The profiling captures runtime behavior including system calls, process IDs, and file path access patterns. It also identifies the main process that starts the container as the entry point and uses it to determine which packages are reachable through their dependency relationships. 3. **Path matching and reachability determination** - Endor Labs correlates the results from both steps by comparing the extracted dependency file paths against the file access patterns captured during profiling, then assigns each dependency a reachability status based on whether the application accessed it during execution. Run the following command with the `--os-reachability` flag to include container reachability analysis in the scan. ```bash theme={null} endorctl container scan \ --namespace= \ --image= \ --project-name= \ --os-reachability ``` You can also run container scans with OS reachability using GitHub Actions. See [Scan containers with OS reachability](/setup-deployment/ci-cd/scan-with-github-actions#scan-containers-with-os-reachability) for details. ### Image qualification Before dynamic profiling begins, Endor Labs performs a series of image qualification checks to determine if the container image is suitable for profiling. These checks include: * **Image size** - Verifies that the uncompressed image size does not exceed the configured limit. The default limit is 10 GB. Use the `--profiling-max-size` flag to adjust this limit. * **Runnability** - Runs the container to check that it starts without errors. If the container exits with an error, the error details appear in the CLI output and surfaced in the Endor Labs user interface. If the image fails any of the qualification checks, the scan skips dynamic profiling and proceeds without reachability analysis. To determine reachability for Chainguard images, scan application images built on top of a base image. ### Determine container reachability using Tetragon events If your Kubernetes cluster runs [Tetragon](https://tetragon.io/), you can use its events as the profiling data source. Your application runs from the original image as a regular pod and does not require image changes or privileged access. Before you run these commands, ensure that: * Tetragon runs in the cluster as a DaemonSet. * A cluster administrator can apply the tracing policy. * You have `kubectl` access to the Tetragon pods to collect the recorded events. Follow these steps to collect Tetragon events and use them to determine OS package reachability. 1. Apply a tracing policy that captures file access events. Endor Labs processes events from the following kernel functions, so hook them in the policy: * `security_file_open`: File opens. * `security_file_permission`: File reads and writes. * `security_mmap_file`: Files mapped into memory, such as shared libraries. * `security_inode_getattr`: File attribute checks. * `security_file_truncate`: File truncation on Linux kernel 6.2 and later. * `security_path_truncate`: File truncation on older kernels. You can trace additional functions whose events include file path information. Add a selector that filters out host namespace events so the policy records activity from containers only. You can add path filters to reduce event volume, but they limit the profiling data that Endor Labs can analyze. The following example shows one hook with the host namespace selector. For the complete policy syntax, refer to the [Tetragon documentation](https://tetragon.io/docs/concepts/tracing-policy/). ```yaml theme={null} apiVersion: cilium.io/v1alpha1 kind: TracingPolicy metadata: name: "container-file-profiling" spec: kprobes: - call: "security_file_open" syscall: false return: true args: - index: 0 type: "file" returnArg: index: 0 type: "int" returnArgAction: "Post" selectors: - matchNamespaces: - namespace: Pid operator: NotIn values: - "host_ns" ``` 2. Identify the Tetragon agent pod on the same node as your application, because each agent records events only from the node it runs on. ```bash theme={null} kubectl get pods -n -l app.kubernetes.io/name=tetragon -o wide ``` * Replace `` with the namespace where Tetragon runs. 3. Start collecting events from that agent pod into a local `tetragon.ndjson` file. The command streams events continuously and does not exit on its own. For other ways to collect Tetragon events, refer to the [Tetragon documentation](https://tetragon.io/docs/concepts/events/). ```bash theme={null} kubectl exec -n -c tetragon -- tetra getevents -o json > /tetragon.ndjson ``` * Replace `` with the agent pod from the previous step. * Replace `` with the namespace where Tetragon runs. * Replace `` with the local directory that stores the collected events. 4. Run your tests or exercise the application while the collection runs. When you finish, stop the collection with `Ctrl+C`. 5. Run `endorctl container scan` with the path to the directory that contains the collected profiling data, and OS reachability enabled. ```bash theme={null} endorctl container scan \ --image=: \ --profiling-data-dir= \ --project-name= \ --os-reachability ``` ### Container reachability options You can run the `endorctl container scan --os-reachability` command with the following options. ## Container reachability status The container reachability status indicates whether the application used a dependency during runtime profiling or whether Endor Labs could not determine its usage. * **Reachable** - The dependency is observed in runtime signals or confidently inferred through correlation analysis. * **Potentially reachable** - The dependency has not been observed during profiling, and there is no correlation evidence of its usage. However, its usage cannot be definitively ruled out without additional analysis, such as extended runtime monitoring. * **Unreachable** - The dependency was not observed during profiling and has no path from the container image's entry point to it. ### Recommended approach for prioritizing remediation Use reachability information to prioritize vulnerability remediation effectively. The following table provides recommended actions based on the combination of vulnerability severity and reachability status. ## View container reachability results After running a container scan with reachability analysis, you can view the profiling status, reachability results, and error details for each container image in the Endor Labs user interface. 1. Select **Containers** from the left sidebar. 2. Select a container image to view its details. 3. The **Container Reachability Status** column shows the profiling status for each container image. **Important** The following table describes the status icons for container reachability. | Status | Description | | -------------- | --------------------------------------------------------- | | ● | Container profiling succeeded. | | ▲ | Container profiling failed. | | N/A | Container was not profiled. | | ⊖ | Container image requires additional configuration to run. | 4. Select a container image to view its details. 5. Select **Reachability Analysis** to view profiling details such as status, profiling type, application type, duration, and entry point package. Reachability analysis with successful container profiling If profiling failed, the error details are also displayed. Reachability analysis with profiling error details 6. Select **View Details** to inspect the findings associated with the container image. Each finding displays the reachability status of its dependency as an attribute label. Findings with reachability attribute labels ## Filter container findings by reachability You can filter findings across all projects by their reachability status. 1. Select **Findings** from the left sidebar. 2. Select **Attributes**, and in the **Reachable Dependency** filter, select **Yes**, **Potentially**, or **No** to narrow down findings by reachability status. ## Limitations Keep the following limitations in mind when using container reachability analysis: * **Code coverage**: The scan does not detect dependencies accessed after the profiling window ends. * **OS packages**: Container reachability analysis applies only to OS-level packages. It identifies which OS packages the application uses at runtime but does not analyze specific vulnerable functions within those packages. Use [Software Composition Analysis reachability](/scan/sca/reachability-analysis) to assess the runtime relevance of application dependencies. * **Windows not supported**: Container scanning and reachability are not supported on Windows. * **Tar image paths**: Dynamic profiling is not supported for container images referenced with a tar path. ## Troubleshoot issues * Verify that the container image runs successfully by using the `docker run` command. * Check whether the container requires specific environment variables or mounted volumes to start correctly. Use the `--env` and `--volume` flags to provide them during the scan. * Ensure that the container does not depend on interactive input during startup or execution. * Use the `--entrypoint` flag to override the container entry point if the default entry point causes issues. * Check the container's startup performance to ensure it initializes within the expected time frame. * Verify that the container has network connectivity if it depends on external services. * Review the container logs to identify any errors or issues that occur during startup. No. Container reachability is not supported on Windows hosts or for Windows container images. * Check whether the uncompressed image size exceeds the configured limit. The default limit is 10 GB. * Use the `--profiling-max-size` flag to increase the limit if needed. **Possible Causes**: * The application might access the dependency only after the profiling window ends. * The dependency may require specific HTTP endpoints or actions that are not triggered during profiling. * The dependency might be loading slowly or initialized only under specific conditions. * Startup optimizations may delay the actual use of the dependency until after profiling completes. * The dependency may not have a direct path from the container image's entry point. **Solutions**: * Review the typical application startup time to determine whether the application loads dependencies later in the process. * Consider whether specific operations or workflows trigger the use of these dependencies. * Use the `--env`, `--volume`, or `--publish` flags to provide the container with the configuration it may require to exercise more code paths during profiling. * Use container reachability results together with threat modeling to better assess overall security risk. # Container registry scanning Source: https://docs.endorlabs.com/scan/containers/container-registry-scan/index Beta
List and scan container images directly from a registry using filters and scan plans. A container registry is a centralized service that stores and distributes your container images. Endor Labs lets you scan images directly from your registry, giving you full visibility into the security posture of your containerized workloads at scale. You can discover images across repositories, control the scope of your scans, and skip images you already scanned to avoid redundant work. You can also run consistent scans over time using saved scan plans. A scan plan is a JSON file that defines the set of container images to scan, along with the registry and filters used to select them. It acts as a predefined template for selecting container images that you can verify and test ahead of time before the actual registry scan runs. Once saved, you can reuse the scan plan to scan the exact same set of images without querying the registry again, making recurring or batch scans consistent and easier to share across runs or environments. With registry scanning, you can list all repositories and tags, or a filtered subset, in a registry without manually specifying each image. You can save an enumerated image list as a scan plan and reuse it later so the command scans the same set of images without re-querying the registry each time. Endor Labs supports the following container registries: * AWS ECR * Azure ACR * Docker Hub * GitHub Container Registry (GHCR) * Google Artifact Registry (GAR) * Harbor * JFrog Artifactory * Quay * Generic OCI-compliant registries Use the `endorctl container registry` commands to list and scan images stored in your registry. * [**List images from a registry**](#list-command): Use `endorctl container registry list` to preview which images match your filters before scanning. This lets you verify the scope and adjust filtering parameters such as `--include`, `--exclude`, `--recent`, and `--limit`. You can also save the results as a scan plan for the scan step. * [**Scan images from a registry**](#scan-command): Use `endorctl container registry scan` to enumerate and scan container images from a registry in a single step. You can also provide a saved scan plan from the list command instead of enumerating the registry again. Use a scan plan when you want to review the list of images before scanning. The scan plans make it easier to reuse these pre-qualified combinations of scanned parameters and ensure consistent results. **Prerequisites for AWS ECR, Azure ACR, and Google Artifact Registry scans** * **AWS ECR**: Install and configure the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). * **Azure ACR**: Install and configure the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli). * **Google Artifact Registry**: Install the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install). Run `gcloud auth application-default login` to authenticate the Artifact Registry API, then run `gcloud auth configure-docker -docker.pkg.dev` to configure the Docker credential helper for image pulls. Replace `` with your registry region, such as `us-west2`. ## List command The list command connects to your registry, enumerates container images based on your configured filters, and prints a summary with a table of image paths. You can also save the results as a scan plan to reuse with the scan command. ```bash theme={null} endorctl container registry list --type= [options] ``` You can apply filters such as `include`, `exclude`, `recent`, and `limit` to narrow down the images returned. If you provide a namespace and API credentials, the saved plan automatically excludes already scanned images, so it is ready to scan only new or updated images. The command applies filters in the following order: 1. **include** 2. **exclude** 3. **recent** 4. **limit** You can use the `endorctl container registry list` command with the following flags. ## Scan command The scan command runs Endor Labs container scans on a set of images. You can pass a saved scan plan from the list command or enumerate the registry with the same filter flags as list. The command pulls each image if needed, runs the scan, and by default removes pulled images after scanning. You must provide `--namespace` and API credentials. Images that are already scanned are automatically skipped. * Scan using a saved scan plan: ```bash theme={null} endorctl container registry scan --namespace= --scan-plan= [options] ``` * Scan using a registry type. When you do not use `--scan-plan`, pass `--type`. ```bash theme={null} endorctl container registry scan --namespace= --type= [options] ``` You can use the `endorctl container registry scan` command with the following flags. ### Supported container registries The `endorctl container registry list` and `endorctl container registry scan` commands support the following container registries. Use the **Registry\_type** value for `--type` and the **Registry\_host** value for `--host`. You must specify the registry host with `--host` when you use Azure ACR or JFrog registries. For Google Artifact Registry, you must specify the region-specific host with `--host`, such as `us-west2-docker.pkg.dev`, and the Google Cloud project with `--registry-namespace`. For Quay registries, set `--host` only for self-hosted instances. You must also specify `--registry-namespace` with the Quay user or organization name to enumerate repositories. ## Output format The list and scan commands both produce output that includes summary lines and, when there are image rows, a table. The scan command shows this when you set `--show-scan-plan`. If any image rows remain after filters, the command prints a table with the following columns: ### Scan plan output The scan plan is a JSON file written by the `endorctl container registry list` command with `--save-as-plan` and read by the `scan` command with `--scan-plan`. When you run list with `--namespace` and API credentials, the saved plan excludes images that Endor Labs already scanned so that it is ready to scan only new or unscanned images. The structure is: ```yaml expandable theme={null} parameters: registry_type: string # required server: string # optional namespace: string # optional account: string # optional. Used only for Docker Hub and GHCR. repo_key: string # optional. Used only for JFrog. architecture: string # optional include: string # optional exclude: string # optional recent: string # optional limit: integer # optional include_untagged: boolean # optional include_untagged_only: boolean # optional validate_tag_digest: boolean # optional timeout_seconds: integer # required counts: repositories: integer tags: integer untagged_manifests: integer # optional matching_repositories: integer # optional matching_tags: integer # optional matching_untagged: integer # optional ignored_repositories: integer # optional ignored_tags: integer # optional ignored_untagged: integer # optional digest_validated_tags: integer # optional digest_mismatch_tags: integer # optional digest_lookup_errors: integer # optional images: # array - path: string # full image reference, tag or digest created: string updated: string multi_arch: boolean # optional arch: string # optional multi_arch_digest: string # optional ``` ## Container registry scanning with AWS ECR The following commands use AWS ECR to show how to list images, apply filters, save a scan plan, and run scans. Use the appropriate `--type`, `--host`, and `--registry-namespace` values for other registries. See [supported container registries](#supported-container-registries) to learn more. * List all images in an AWS ECR registry. ```bash theme={null} endorctl container registry list --type aws.ecr ``` * Filter images updated in the last 7 days, include only tags matching `latest`, and exclude release candidate tags. ```bash theme={null} endorctl container registry list --type aws.ecr --recent 7d --include '.*:latest' --exclude '.*:-rc.*' ``` * Save the generated image list to a JSON scan plan file for use with the `container registry scan` command. ```bash theme={null} endorctl container registry list --type aws.ecr --save-as-plan registry-scan-plan.json ``` * List images including untagged manifests. ```bash theme={null} endorctl container registry list --type aws.ecr --include-untagged ``` * List only images that match a preferred architecture such as `arm64` when the repository contains multi-architecture images. ```bash theme={null} endorctl container registry list --type aws.ecr --architecture arm64 ``` * Scan images defined in a previously saved scan plan file. ```bash theme={null} endorctl container registry scan --namespace demo --type=aws.ecr --reauth --scan-plan aws_ecr_scan_plan.json ``` * AWS ECR authenticates using the AWS SDK default credential chain, which includes environment variables, shared credential files, and IAM roles. * For Docker Hub, use `--type=dockerhub` and omit `--reauth` because it requires access to Docker Hub credentials for automated reauthentication. * For Quay, use `--type=quay` and provide `--registry-namespace` with your Quay user or organization name. Omit `--reauth` because Quay requires manual login. ## Container registry scanning with Google Artifact Registry The following commands use Google Artifact Registry to show how to authenticate, list images, save a scan plan, and run scans. GAR requires both `--host` and `--registry-namespace`: * Set `--host` to the region-specific registry host in the form `-docker.pkg.dev`, such as `us-west2-docker.pkg.dev`. * Set `--registry-namespace` to the Google Cloud project that contains the registry. GAR uses two credential sources. Endor Labs reads repository and tag metadata through the Artifact Registry API using your Google Application Default Credentials, and pulls image content through the Docker credential helper. * Authenticate the Artifact Registry API with Application Default Credentials, then configure the Docker credential helper for your registry location. ```bash theme={null} gcloud auth application-default login gcloud auth configure-docker us-west2-docker.pkg.dev ``` * List all images in a Google Artifact Registry project. ```bash theme={null} endorctl container registry list --type gar --host us-west2-docker.pkg.dev --registry-namespace my-gcp-project ``` * Include only images that match a repository path. ```bash theme={null} endorctl container registry list --type gar --host us-west2-docker.pkg.dev --registry-namespace my-gcp-project --include 'my-org/.*' ``` This pattern matches image paths such as `us-west2-docker.pkg.dev/my-gcp-project/my-org/app:latest` and `us-west2-docker.pkg.dev/my-gcp-project/my-org/db:1.2.3`. * Save the enumerated image list to a scan plan file. ```bash theme={null} endorctl container registry list --type gar --host us-west2-docker.pkg.dev --registry-namespace my-gcp-project --save-as-plan gar-scan-plan.json ``` * Scan the images defined in the saved scan plan. ```bash theme={null} endorctl container registry scan --namespace demo --type gar --host us-west2-docker.pkg.dev --registry-namespace my-gcp-project --scan-plan gar-scan-plan.json ``` Do not use `--reauth` with GAR. Automatic credential refresh is supported only for AWS ECR and Azure ACR. Refresh GAR credentials by re-running `gcloud auth application-default login`. ## Troubleshooting * Ensure your registry credentials are valid and that the registry type and host are correct. Use `--reauth` to refresh credentials when using AWS ECR or Azure ACR. * For Docker Hub, GHCR, and Quay, verify the environment variables or log in with the registry's CLI. * For Quay, use `docker login` with an OAuth token. * For Google Artifact Registry, confirm that you ran `gcloud auth application-default login` for the Artifact Registry API and `gcloud auth configure-docker -docker.pkg.dev` for image pulls. Do not use `--reauth` with GAR. Refresh credentials by re-running `gcloud auth application-default login`. * For Azure ACR and JFrog, verify that you set `--host`. * The command excludes images that Endor Labs already scanned only when you run list with `--namespace` and valid API credentials. Without them, the saved plan includes all matching images. * Re-run `endorctl container registry list` with `--namespace` and `--exclude-scanned`, save a new plan with `--save-as-plan`, then run the scan command with that plan. Run the list command with your registry details and `--save-as-plan` to save the enumerated images to a JSON file. ```bash theme={null} endorctl container registry list --type artifactory --host jfrog-host --registry-namespace repo-key --save-as-plan registry-scan-plan.json ``` Replace `jfrog-host` with your JFrog host and `repo-key` with your repository key. Run the list command with `--type=quay` and `--registry-namespace` set to your Quay user or organization name. ```bash theme={null} endorctl container registry list --type=quay --registry-namespace myorg ``` For a self-hosted Quay or Harbor instance, set `--host` to your registry host. ```bash theme={null} endorctl container registry list --type=quay --host http://localhost:8080 --registry-namespace myorg ``` Replace `myorg` with your Quay user or organization name and `http://localhost:8080` with your self-hosted registry URL. # Container Scanning Source: https://docs.endorlabs.com/scan/containers/index Scan container images for vulnerabilities and secure your deployments. **Important** Container scanning now has its own dedicated command: `endorctl container scan`. The `endorctl scan --container` commands are deprecated and will be removed after a three-month deprecation period. Migrate to the `endorctl container scan` command to ensure continued compatibility. For more details, see [Container scan commands migration guide](/scan/containers/container-migration). Containers help developers create, test, and deploy applications in a consistent environment. Container images include standalone or executable files encompassing files, libraries, and dependencies needed to run a container. They include several open-source software, making them vulnerable to open-source risks. Gaining visibility into container images is essential to identify and prioritize risks or maintain compliance obligations. Endor Labs container scan detects and reports known vulnerabilities and other risks in: * **Operating system packages:** Packages installed through the container's base OS package manager. * **Programming language packages:** packages installed through language-specific package managers. * **Libraries and dependencies:** Static and dynamic libraries and runtime dependencies required by the application. Additionally, it generates an **Software Bill of Materials (SBOM)** that details all components, their versions, and associated metadata, providing a complete inventory of the container's contents. Upgrade to endorctl version 1.6.734 or higher to ensure accurate container scan results. ## How Endor Labs derives container findings Endor Labs’ container scanning results rely on OVAL feeds from distributions. OVAL feeds provide accurate and vetted vulnerability data, while excluding disputed or irrelevant entries. OS dependency results are based on data from distribution developers. For language package dependencies, we complement published data with our proprietary research. Endor Labs fetches the container image from a container registry or loads it from a local file to scan containers. It then proceeds to extract the layers of the container image. It traverses the filesystem of each layer to identify files and directories. It looks for known package manager and metadata files to gather information about installed packages and their versions. It identifies the components and dependencies within the image and presents the findings in CLI and the Endor Labs user interface. Endor Labs categorizes the severity of vulnerabilities detected in container scans as follows: * Use the severity assigned by the distribution, if it exists. * Use the NVD severity if the distribution does not provide the severity. * Report the vulnerability as `Medium` if there is no severity assigned by the distribution, or the NVD severity is not known or can't be matched. Endor Labs doesn't report disputed vulnerabilities withdrawn from NVD. ### Discover base images of containers A container image is often built upon a base image that is a foundational layer including an operating system and other essential components. It's crucial to understand what's in the base image for a thorough security assessment. You can distinguish the base image related vulnerabilities from the application layer using any of the following methods: * **Scan Sequence**: First, scan the base image. Then, scan any subsequent images built on that base image to distinguish vulnerabilities specific to the base image from those introduced by the other layers. * **Docker file label**: Set the label directly in your Dockerfile with a command, for example, `LABEL org.opencontainers.image.base.name="openjdk:17-slim"`. * **Build time label**: Include the base image label during the build process with the `--label` flag, specifying both the base image and, optionally, its exact version via SHA256 hash. For example: ```bash theme={null} docker build -t tictactoe:latest --label "org.opencontainers.image.base.name=openjdk@sha256:eddacbc7e24bf8799a4ed3cdcfa50d4b88a323695ad80f317b6629883b2c2a78" . ``` Base image ## Verify access to container registries If the container image is in a private Docker registry, you must authenticate the container client before the scan. Here are a few commands to authenticate the container client. ```bash theme={null} docker login -u -p ``` [Learn more about Docker authentication](https://docs.docker.com/reference/cli/docker/login/) ```bash theme={null} podman login -u -p ``` [Learn more about Podman authentication](https://docs.podman.io/en/stable/markdown/podman-login.1.html) [Endor Labs Podman troubleshooting](https://docs.endorlabs.com/troubleshooting/podman/) You must configure the containerd config file to authenticate with the container registry. [Learn more about containerd authentication](https://github.com/containerd/containerd/blob/main/docs/cri/registry.md) ## Supported languages and package managers The dependencies associated with the following list of components are identified in the endorctl scan. Endor Labs recognizes only the installed dependencies. Declared but uninstalled dependencies in the container image are not recognized. ## Limitations of container findings * Scanning Windows containers is not supported. * Docker file scans are not currently supported. * Container registry direct integrations are not currently supported. * Support for scanning binary files inside a container is limited. * Endor scores are not calculated for findings reported in the container scan. # Instrumented container reachability Source: https://docs.endorlabs.com/scan/containers/instrumented-reachability/index Beta
Learn how to derive advanced OS package reachability when your container depends on complex external services. Instrumented container reachability is an advanced OS package reachability mode that embeds a runtime sensor in your container image to record how your application uses the image in a real environment. Use it when your container relies on complex external services that you cannot exercise during a short local run, so that reachability results then reflect actual usage. Use instrumented reachability when: * The container has complex external dependencies such as databases, message queues, third-party services that you cannot realistically exercise in a local ephemeral run. * You want profiling to happen in a realistic environment, such as staging, that mirrors production traffic. * You already have integration or end-to-end tests and want reachability to reflect those tests. You can run instrumented container reachability using either [Kubernetes](#instrumented-reachability-kubernetes) or [Docker](#instrumented-reachability-docker). Run the container scan using the new `endorctl container scan` command. The `endorctl scan --container` command does not support container reachability. ### Prerequisites To perform instrumented container reachability analysis, ensure that: * Enable container scanning [using the `--os-reachability` flag](/scan/containers/container-reachability). * Install and authenticate [endorctl](/developers-api/cli/install-and-configure). * You have installed Docker daemon `dockerd` on the host and it runs and is accessible to the current user without elevated privileges. For example, `docker images` should work without `sudo`. * The negotiated Docker API version between the client and server is `1.48` or higher. * You must run the scan from either a Linux or a macOS host machine. Endor Labs supports container reachability on both amd64 and arm64 architectures. To run the instrumented container images, you need either Docker or Kubernetes, based on your setup: * **Docker**: Docker daemon and Docker CLI is available and you can run the instrumented image locally. * **Kubernetes**: You have configured `kubectl` with access to your cluster so you can deploy and run the instrumented image in a pod. ### Determine instrumented container reachability using Kubernetes Follow these steps to scan the original image, collect runtime profiling data, and determine reachability for containers using Kubernetes. 1. Run `endorctl container instrument` to create a new image with a lightweight sensor injected into the filesystem. The resulting image will have `-instrumented` appended to the tag. ```bash theme={null} endorctl container instrument \ --image=: \ --app-stop-signal=QUIT \ --load-instrumented-image=true ``` * `--image`: Original container image to instrument. * `--app-stop-signal`: Signal used to stop the application. The sensor needs this so it can flush profiling data before the container exits. * `--load-instrumented-image`: Loads the instrumented image into your local Docker runtime so Kubernetes can reference it. * To instrument a multi-arch image for specific platforms, run `endorctl container instrument` with the `--platform` flag. ```bash theme={null} endorctl container instrument \ --image= \ --app-stop-signal=QUIT \ --load-instrumented-image=true \ --platform=linux/arm64,linux/amd64 ``` 2. Define how the instrumented image runs in a manifest. Create a manifest file such as `demo-manifest-file.yaml` to identify your workload. In the manifest, reference the instrumented image from step 1 and use a pod name and container name you can reuse later. You can also add `env`, `volumes`, and other options as needed for your application. ```yaml theme={null} apiVersion: v1 kind: Pod metadata: name: spec: restartPolicy: OnFailure containers: - name: image: ports: - containerPort: hostPort: securityContext: privileged: true ``` * Set `securityContext.privileged` to `true` so the profiling sensor can run. * Set `restartPolicy` to `OnFailure` so that the pod does not restart automatically after you stop the app to generate the report. 3. Deploy the instrumented image to Kubernetes. The application runs normally while the sensor observes file access and process activity while the application runs. ```bash theme={null} kubectl apply -f kubectl get pods ``` Replace ``, ``, and `` with the values from your manifest. * If you need to access the application locally, run: ```bash theme={null} kubectl port-forward pod/ : ``` * You can also run your tests or interact with the application normally. The profiling sensor will capture runtime activity. 4. After you finish testing, send the `--app-stop-signal`, for example, `QUIT`, to stop the application gracefully. This signal triggers the profiling sensor to write the `creport.json` file and generate the profiling data. ```bash theme={null} kubectl exec -it -c -- sh -c "kill -QUIT 1" ``` 5. The sensor writes a profiling report to a known artifacts directory inside the container. * Verify that the `creport.json` file exists in the container: ```bash theme={null} kubectl exec -it -c -- sh -c "ls -ls /opt/_instrumented/artifacts" ``` 6. Create a local directory and copy the report to it. The sensor writes `creport.json` only after you stop the application. To get profiling data without stopping it, copy only `mondel.ndjson`. ```bash theme={null} # Create output directory mkdir -p collect_output # Copy the profiling data from creport.json kubectl cp :/opt/_instrumented/artifacts/creport.json collect_output/creport.json -c # Copy the profiling data from mondel.ndjson kubectl cp :/opt/_instrumented/artifacts/mondel.ndjson collect_output/mondel.ndjson -c ``` * To verify the copy, run: ```bash theme={null} ls -la collect_output/ ``` * Alternatively, you can use `endorctl container collect` to stop the running application and retrieve the profiling report from the instrumented container into a local directory. Skip steps 4, 5, and 6 if you are using this command. ```bash theme={null} endorctl container collect \ --dynamic-profiling-data=true \ --output-dir=collect_output \ --image= ``` * Set `--dynamic-profiling-data` to `true` to collect profiling data from the instrumented container. * Set `--output-dir` to the local directory that stores the collected data. The command creates a subdirectory under this path `cluster/pod/container`. Use that path for `--profiling-data-dir` in the next step. 7. Run `endorctl container scan` with the path to the directory that contains the collected profiling data, and OS reachability enabled. Endor Labs loads the report, maps runtime files to OS packages, and marks the corresponding packages as reachable. ```bash theme={null} endorctl container scan \ --image=: \ --profiling-data-dir=collect_output \ --project-name= \ --os-reachability ``` 8. Remove the pod after completing the analysis: ```bash theme={null} kubectl delete pod ``` 9. Optionally, publish the instrumented image to a registry using the `--publish` flag. The command pushes the image only if the Docker daemon is already authenticated with the target registry. `endorctl` will not attempt to re-authenticate with the container registry. ```bash theme={null} endorctl container instrument \ --image= \ --app-stop-signal=QUIT \ --load-instrumented-image=true \ --publish=true ``` ### Determine instrumented container reachability using Docker Follow these steps to scan the original image, collect runtime profiling data, and determine reachability for containers using Docker. 1. Run `endorctl container instrument` to create a new image with a lightweight sensor injected into the filesystem. At runtime, the sensor writes `mondel.ndjson` to `/opt/_instrumented/artifacts/` while the application runs. When the application stops, the sensor also writes `creport.json` to the same location. By default, the command saves the image as `instrumented-image.tar`. To use a different output path, pass `--output-image-tar`. ```bash theme={null} endorctl container instrument \ --image : \ --load-instrumented-image \ --app-stop-signal ``` * `--image`: Container image you want to instrument. * `--app-stop-signal`: Signal that stops the application so the sensor can flush profiling data before the container exits. * `--load-instrumented-image`: Loads the instrumented image into Docker so you can run it with `docker run`. 2. Run the instrumented image in Docker with `--privileged` so the sensor can use `ptrace` to watch file access. Docker blocks `ptrace` in unprivileged containers by default. You can run tests or interact with the application while the container runs. The sensor observes file access and process activity. ```bash theme={null} docker run -d \ --name \ --privileged \ :-instrumented ``` You can also pass: * `-e KEY=VALUE`, for example `-e PASSWORD=testpassword123`, to provide environment variables your app needs to start. * `-p :`, for example `-p 8080:8080`, to expose ports when you send traffic from your host during profiling. 3. After testing, send the `--app-stop-signal` to stop the application gracefully. This signal triggers the profiling sensor to write the `creport.json` file. The `sleep` gives the sensor time to finish writing. ```bash theme={null} docker kill --signal= sleep 10 ``` 4. Create a local directory and copy the report to it. The sensor writes `creport.json` only after you stop the application. To get profiling data without stopping it, copy only `mondel.ndjson`. ```bash theme={null} mkdir -p ./profile-data # Copy the profiling data from creport.json docker cp :/opt/_instrumented/artifacts/creport.json ./profile-data/ # Copy the profiling data from mondel.ndjson docker cp :/opt/_instrumented/artifacts/mondel.ndjson ./profile-data/ ``` 5. Run `endorctl container scan` with the path to the directory that contains the collected profiling data, and OS reachability enabled. Endor Labs loads the report, maps runtime files to OS packages, and marks the corresponding packages as reachable. If you run the command outside a Git repository, pass `--project-name ` to avoid an initialization error. ```bash theme={null} endorctl container scan \ --image : \ --profiling-data-dir ./profile-data \ --os-reachability \ -n ``` 6. Remove the container after you complete the analysis. ```bash theme={null} docker rm ``` ### Instrumented reachability options You can run the `endorctl container instrument` command with the following options. You can run the `endorctl container collect` command with the following options. ### Troubleshoot issues * Ensure that you send the QUIT signal correctly. * Check that the container has privileged: true in security context. * Verify that the `--app-stop-signal` matches the signal your application handles. * If `creport.json` is missing, copy `mondel.ndjson` from the running container instead. * Run `kind load docker-image ` to load the image into kind. * Push the image to a container registry. The profiling sensor uses `ptrace` to watch file access, which unprivileged containers block by default. Set `securityContext.privileged: true` in the pod manifest. # Scan containers using endorctl Source: https://docs.endorlabs.com/scan/containers/scan-containers-using-endorctl/index Learn how to scan container images using the endorctl container scan command for security vulnerabilities, dependencies, and compliance. Container images contain multiple layers of software dependencies that introduce security risks across the entire software supply chain. The `endorctl container scan` command analyzes container images to identify vulnerabilities in base OS packages, runtime dependencies, and application libraries, providing comprehensive security visibility across all containerized workloads. ## Create finding policies for containers Container base images from untrusted sources may lack proper security audits or fail to comply with organizational standards, increasing the risk of vulnerabilities being exploited. To address this, you can configure a finding policy to detect unauthorised base images and raise a critical finding. For example, to allow only base images that start with `gcp` or `ghcr`, use the [Container policy template](/managing-policies/finding-policies/container-policies) and specify **Base Image Name Regex** as `^gcp`, `^ghcr`. See [Create a finding policy from template](/managing-policies/finding-policies#create-a-finding-policy-from-template) for detailed instructions on creating finding policies. Finding policy template for container base images ## Perform the endorctl scan Endor Labs supports the following methods of scanning container images: * **[Scan container images in a Git repository](#scan-container-images-in-a-git-repository)**: Scan images built within your repository using a Dockerfile. * **[Scan container images as a standalone project](#scan-container-images-as-a-standalone-project)**: Scan base or golden images that are shared across multiple repositories or applications. * **[Scan container image tarball](#scan-container-image-tarball)**: Scan images saved as tar files, such as base images exported from Docker, to generate dependency, SBOM, and vulnerability reports. * **[Scan images from a container registry](/scan/containers/container-registry-scan)**: List and scan images directly from a registry such as AWS ECR, Azure ACR, Docker Hub, GHCR, or JFrog Artifactory. ### Scan container images in a Git repository Run the following command to scan a container image built in a specific repository. Specify the project path using the `--path` argument and the container image name using the `--image` argument. This associates the container with the Git repository and branch of the project. ```bash theme={null} endorctl container scan --image= --path=users/janedoe/endorlabs/npm/exampleproject ``` You can also scan multiple container images as part of a single repository. ```bash theme={null} endorctl container scan --image= --path=users/janedoe/endorlabs/npm/exampleproject endorctl container scan --image= --path=users/janedoe/endorlabs/npm/exampleproject endorctl container scan --image= --path=users/janedoe/endorlabs/npm/exampleproject ``` You can tag findings with the corresponding container image name and tag. This lets you filter container-related findings in the user interface or through the API. ```bash theme={null} endorctl container scan --image= --path=users/janedoe/endorlabs/npm/exampleproject --finding-tags= ``` ### Scan container images as a standalone project Run the following command to scan a container image from a registry. Specify the project name using the `--project-name` argument, and the container image name and tag using the `--image` argument. ```bash theme={null} endorctl container scan --image= --project-name= ``` To keep multiple versions of a container image in a container-only project, include the `--as-ref` flag. ```bash theme={null} endorctl container scan --image= --project-name= --as-ref ``` You can tag findings with the corresponding container image name and tag. This lets you filter container-related findings in the user interface or through the API. ```bash theme={null} endorctl container scan --project-name= --image= --as-ref --finding-tags= ``` **Important** To associate a container scan with an existing SCA scan for a project, you must use the `--path` argument specifying the same project path used for the SCA scan. You cannot associate a container scan with an SCA scan for a project using the `--project-name` parameter. ### Scan container image tarball You can save a container image as a tarball and scan it with endorctl to generate a report containing dependencies, SBOM details, and security findings. 1. Ensure that you have the container image available locally. ```bash theme={null} docker pull alpine:latest ``` 2. Export the image to a tarball file. ```bash theme={null} docker save alpine:latest -o alpine-latest.tar ``` 3. Perform the endorctl scan. ```bash theme={null} endorctl container scan --image=alpine:latest --project-name= --image-tar=/absolute/path/to/alpine-latest.tar ``` * `--image-tar` must point to the absolute path of the tarball file. * `--image=` is optional but recommended. It explicitly identifies the container image inside the tarball. ## Perform container scan in CI pipelines You can integrate container scanning into CI pipelines to automatically detect vulnerabilities and ensure the security of container images during the build and deployment process. To scan containers in CI pipelines using GitHub Actions, set the `scan_container` parameter to `true` in the GitHub Actions script. Additionally, you must provide the `image` parameter with the container image you want to scan. See [Performing scans in CI/CD pipelines](/deployment/ci-scans) for more information. # Scan GitHub Actions Source: https://docs.endorlabs.com/scan/github-actions/index Scan the GitHub Actions used in your workflow files for vulnerabilities, malware, and risky configuration. GitHub Actions scanning analyzes third-party Actions your workflows depend on. It is not the same as [Scanning with GitHub Actions](/setup-deployment/ci-cd/scan-with-github-actions), which runs Endor Labs inside a CI job on GitHub-hosted runners. Here you analyze Actions referenced in workflow files under `.github/workflows/` (including subdirectories), relative to the directory you scan. Scanning those dependencies gives you visibility into supply chain risk in CI. You can detect known vulnerabilities, malware, and unsafe patterns in workflow YAML. ## How Endor Labs scans your workflows Endor Labs discovers workflow files only under `.github/workflows/` relative to the directory you scan (`--path`, default the current directory). It walks that folder recursively and includes files with a `.yml` or `.yaml` extension. Workflow files outside that tree are not part of discovery. From those files, Endor Labs resolves each `uses:` reference as a GitHub Actions dependency and models each action as a package with direct and transitive dependencies. Endor Labs also evaluates workflow YAML with analytics and raises findings for risky configurations. ## What Endor Labs detects The following table summarizes the main areas. For policy names and severities, see [GitHub Action policies](/platform-administration/policies/finding-policies/github-action-policies). ## Automate enforcement with action policies [Action policies](/platform-administration/policies/action-policies) determine the automated response when a GitHub Action finding matches. Examples include failing a CI check, adding a PR comment, or sending a notification. Use the [GitHub Actions policy template](/platform-administration/policies/action-policies/templates#github-actions) to create action policies that target workflow-related findings. The template exposes parameters such as finding name (defaults include **Unpinned direct dependency**, **Untrusted code checkout**, and **Imposter commit**) and severity. ## Enable GitHub Actions scanning You can scan GitHub Actions through the Endor Labs GitHub App, Endor Labs GitHub Action, or with endorctl. ### Scan GitHub Actions with GitHub App When you install the [Endor Labs GitHub Cloud App Pro](/setup-deployment/scm-integrations/github-app) or the [GitHub Enterprise Server App](/setup-deployment/scm-integrations/github-app/github-enterprise-app), enable **GitHub Actions** among the scanners. That schedules repository scans that include workflow dependency and posture analysis. See also [Scan capabilities of the Endor Labs GitHub Apps](/setup-deployment/scm-integrations/github-app/scan-with-githubapp). ### Scan GitHub Actions with Endor Labs GitHub Action In your CI workflow, pass `scan_github_actions: true` to the Endor Labs GitHub Action. See [GitHub Action configuration parameters](/setup-deployment/ci-cd/scan-with-github-actions#endor-labs-github-action-configuration-parameters). ### Scan GitHub Actions with endorctl Run the following command to scan the GitHub Actions in your repository. ```bash theme={null} endorctl scan --ghactions ``` The flag enables GitHub Actions workflow scanning. You can combine it with other scan options as needed. The environment variable is `ENDOR_SCAN_GHACTIONS`. For the full CLI reference, see [endorctl scan](/developers-api/cli/commands/scan). ## Limitations of GitHub Actions scanning GitHub Actions scanning has the following limitations: * Endor Labs detects vulnerabilities and dependencies for GitHub Action packages written in JavaScript or TypeScript. * Private GitHub Actions and private reusable workflows referenced from other repositories are not detected. * Test dependencies are not detected for GitHub Action packages. # Scan with Endor Labs Source: https://docs.endorlabs.com/scan/index Explore user-initiated and system-triggered scan types for vulnerabilities, secrets, license issues, malware, and more. Endor Labs automatically runs several scan types in the background to keep your findings current as new security intelligence arrives. These scans are triggered by the system and run without any configuration on your part. * **Analytics scan**: A periodic, automated scan that refreshes findings without any user action. The system runs this scan only when the analytics-check scan detects changes or new vulnerabilities. Applies only to CI and CLI-based projects. You can identify these scans in [Scan history](/inventory-insights/scan-history) by the **analytics** scan type label. * **Analytics-check scan**: An automated, recurring process that checks for changes or newly introduced vulnerabilities. It skips the analytics scan if no changes are detected. Applies only to CI and CLI-based projects. You can identify these scans in [Scan history](/inventory-insights/scan-history) by the **analytics-check** scan type label. * **Finding-refresh scan**: A lean scan that recomputes vulnerability findings using stored dependency metadata, without fetching source code or running a full project scan. It runs automatically after new critical vulnerability data is ingested, so findings are updated without waiting for the next scheduled scan cycle. Finding-refresh scans do not run SCA, secrets, SAST, linter, or analytics scans. They also do not update score, typosquatting, AI SAST, or security review findings. Applies to all project types, including CI, CLI, and agentless app-based projects. You can identify these scans in [Scan history](/inventory-insights/scan-history) by the **finding-refresh** scan type label. Endor Labs provides comprehensive scans to identify security issues across your software supply chain. This following sections cover the different scanning capabilities and how to configure them. Scan open source dependencies for vulnerabilities with reachability analysis. Scan your first-party code for security vulnerabilities. Scan GitHub Actions referenced in your workflows for vulnerabilities, malware, and risky configuration. Scan your codebase for leaked secrets and sensitive data. Scan container images for vulnerabilities and secure your deployments. Scan dependencies for malware and understand how it is detected, classified, and scored. Scan for and govern AI models in your codebase. Identify and manage open source license compliance. Configure scan profiles to customize how your projects are scanned. Scan pull requests as they are raised in your repository. Scan monorepos with Endor Labs using Bazel. Scan large monorepos with strategies for performance and coverage. Manage repository security posture and SCM configurations. # Malware detection Source: https://docs.endorlabs.com/scan/malware/index Understand how malware is detected, classified, and scored in Endor Labs. Endor Labs detects malware in dependencies by scanning the packages used in the project and recognizing known malicious patterns. **Monitoring for known malicious packages:** Endor Labs scans dependencies to identify malware by cross-referencing findings with the Open Source Vulnerability (OSV) database and data from the proprietary malware feed. **Suspicious code behavior:** Endor Labs uses malware detection rules and SAST rules to scan open source package dependencies for suspicious code patterns and behaviors. These rules analyze code structures, detect anomalies, and identify potential threats. ## Detect malware findings Endor Labs provides a set of malware policies designed to identify and manage malicious or suspicious code in your project, ensuring that Endor Labs detects potential security risks early. * The [OSS finding policy](/platform-administration/policies/finding-policies/oss-policies) detects malicious code and findings in your project. You can edit the policy to change the severity and template parameters. * Configure [malware action policy](/platform-administration/policies/action-policies/templates#malware) to specify how detected malware findings should be handled automatically, including notifications, blocking actions, and workflow triggers. * Configure [malware exception policy](/platform-administration/policies/exception-policies/templates#malware) to exclude malware findings under defined conditions. This filters out false positives and keeps the focus on critical risks. ## View malware findings You can view the malware findings, prioritize them, and take corrective action. 1. Select **Projects** from the left sidebar. 2. Select the project for which you want to view the malware. 3. Select **Malware** to view malware findings. Malware findings 4. Select a finding to view the following information: * **Project**: The name of the project where Endor Labs finds the malware, finding policy, categories, and attributes of the project. * **Risk Details**: * Explanation of the finding. * Reasoning explains why Endor Labs classifies the package as malware. * Recommended remediation. * **Metadata**: Contains details such as the vulnerability IDs, ecosystem, package release date, and advisory publication date. Malware findings side panel * **Dependency Path**: Shows how upstream dependencies reach the malicious package version. Malware finding dependency path tab 5. Click **View Details**, to view the details of the malware finding. Malware findings view details ## Check for malicious package versions You can check whether specific package versions are flagged as malicious by querying the Endor Labs malware database. Run the following command to make an API query. The namespace must be `oss`, and you can pass one or more package versions in the `names` list. ```bash theme={null} endorctl api create -r QueryMalware -n oss -d '{"spec":{"package_version_names":{"names":["://@"]}}}' ```

Restrictions on using the QueryMalware API

The API is restricted for use with certain conditions. See [Permitted use of malware detection data](#permitted-use-of-malware-detection-data) for more information. For example, run the following command to check whether the `MailBee@12.3.3` package version is malicious. ```bash theme={null} endorctl api create -r QueryMalware -n oss -d '{"spec":{"package_version_names":{"names":["nuget://MailBee@12.3.3"]}}}' ``` The command returns a json response with details about the package version and the reasons for marking it as malicious. ```json expandable theme={null} { "meta": { "create_time": "2025-09-02T04:40:29.773434484Z", "kind": "QueryMalware", "name": "malware for ", "update_time": "2025-09-02T04:40:29.773434744Z", "version": "v1" }, "responses": { "values": { "nuget://MailBee@12.3.3": { "list": { "objects": [ { "meta": { "create_time": "2025-06-27T07:39:08.576Z", "index_data": { "data": [ "@ancestor=oss" ], "tenant": "oss" }, "kind": "Malware", "name": "Malicious code in MailBee (nuget)", "update_time": "2025-09-02T01:41:51.930710821Z", "upsert_time": "2025-09-02T01:41:51.930710821Z", "version": "v1" }, "spec": { "additional_notes": [ "\n---\n_-= Per source details. Do not edit below this line.=-_\n" ], "advisory_last_updated": "2024-06-25T13:30:02Z", "advisory_published": "2024-06-25T13:30:02Z", "aliases": [ "MAL-2024-4540" ], "cwe_id": "CWE-506", "ecosystem": "ECOSYSTEM_NUGET", "malware_detected_on": "2024-06-25T13:30:02Z", "package_name": "MailBee", "purl": "pkg:nuget/MailBee", "source": "MALWARE_SOURCE_OSV", "status": "MALWARE", "summary": "Malicious code in MailBee (nuget)", "version": { "osv_id": "MAL-2024-4540", "version": "12.3.3" } }, "tenant_meta": { "namespace": "oss" }, "uuid": "685e4a9c9787b3b77c7ac0c0" } ], "response": { "next_page_id": "685e4a9c9787b3b77c7ac0c0", "next_page_token": 1 } } } } }, "spec": { "package_version_names": { "names": [ "nuget://MailBee@12.3.3" ] } }, "tenant_meta": { "namespace": "oss" }, "uuid": "68b6753d19d009449113d065" } ``` ## Permitted use of malware detection data The following sections describe the permitted use of malware detection data across Endor Open Source Core (OSS Core), Open Source Pro (OSS Pro), and Package Firewall licenses. ### What's included with OSS Core / OSS Pro vs. Package Firewall The following table summarizes the capabilities available with each license. | You want to… | OSS Core / OSS Pro | Package Firewall | | --------------------------------------------------------------- | ------------------ | ---------------- | | See malicious packages found in your scanned repositories | ✓ Included | ✓ Included | | Pull those findings via API into Jira, SIEM, or a dashboard | ✓ Included | ✓ Included | | Fail a build or PR check when a scan finds malware in your code | ✓ Included | ✓ Included | | Query Endor Labs for a package before it enters your codebase | ✕ Not licensed | ✓ Included | | Block or gate package installation based on Endor Labs data | ✕ Not licensed | ✓ Included | | Bulk-retrieve or mirror the Endor Labs malicious-package corpus | ✕ Not licensed ¹ | ✕ Not licensed ¹ | | Redistribute Endor Labs malware data to third parties | ✕ Not licensed ¹ | ✕ Not licensed ¹ | ¹ Bulk export and redistribution are outside the scope of all standard SKUs. If you have a data-integration or OEM requirement, contact your account team. ### Scope of the included capability Malware detection is included with Endor Labs OSS Core and OSS Pro so that you can identify and remediate malicious packages that Endor Labs has detected in the dependencies of repositories you have onboarded and scanned. Findings for your scanned dependencies are yours to consume through the UI, the API, and CI/CD integrations, including exporting them into your own ticketing, SIEM, and reporting systems. Malware detection under OSS Core and OSS Pro is a detection capability. It is scoped to what your scans surface. It is not a license to the broader Endor Labs malicious-package intelligence corpus. ### Restrictions Accordingly, under OSS Core and OSS Pro you may not: * Retrieve, enumerate, or cache malware or malicious-package records that are not associated with a dependency identified in one of your own scanned repositories — including by iterating over package names, versions, ecosystems, registries, or record identifiers. * Build or operate an internal threat intelligence database, index, mirror, or replica of Endor Labs malicious-package data intended to be queried independently of your Endor Labs scan results. * Use Endor Labs malware data as the decision source for a pre-installation or pre-resolution allow/deny control — for example a proxy, registry mirror, package-manager plugin, resolver hook, or admission gate that consults Endor Labs data to decide whether a package may be fetched or installed. * Redistribute, resell, sublicense, or otherwise make available Endor Labs malware data to any third party, or expose it through a service, product, or feed offered to others. * Use Endor Labs malware data to develop, train, benchmark, or improve a competing product or service. ### Pre-installation blocking requires Endor Labs Package Firewall If your goal is to prevent malicious packages from being installed or resolved at all — rather than detecting them after they enter a repository — that capability is delivered by the Endor Labs Package Firewall SKU, which is purpose-built for it and licensed for that use. Contact your account team. ### Enforcement Endor Labs may apply rate limits, quotas, query-scoping, and entitlement checks to API endpoints that return malware data, and may adjust them without notice to enforce the scope described above. Use of the Endor Labs API is also subject to your agreement with Endor Labs and the Endor Labs Acceptable Use Policy, which control in the event of any conflict with this page. # OSS Licenses Source: https://docs.endorlabs.com/scan/oss-licenses/index Identify and manage open source license compliance. Open source software comes with different licenses that define how the software can be used, modified, and distributed. Managing license compliance is essential for organizations to avoid legal risks and ensure proper use of open source components. For generating Notice reports for distribution and for license-centric views and editable license data, see [Licenses](/inventory-insights/licenses/#generate-a-notice-report). ## Policy templates for open source license detection Endor Labs provides the following policy templates for detecting open source license usage. See [Finding policies](/platform-administration/policies/finding-policies) for details on how to create policies from policy templates. ## License types Endor Labs classifies licenses according to industry best practices: * **Restricted**: Licenses with significant usage restrictions. * **Reciprocal**: Licenses that require derivative works or linked code to be shared under compatible terms. * **Copyleft**: Licenses that require derivative works to use the same license. * **Notice**: Licenses that require attribution or notice when distributing the software. * **Permissive**: Licenses that allow broad use with minimal restrictions. * **Unencumbered**: Licenses that dedicate the work to the public domain or grant very broad rights with no material conditions. * **Forbidden**: Licenses that should not be used in your organization. # Pull Request scans Source: https://docs.endorlabs.com/scan/pr-scans/index Scan pull requests created in your repository. Scan pull requests as soon as they are raised in your repository. PR scans detect vulnerabilities in your branch when they are introduced, making it easier to identify and fix them early. PR scans help you to: * Detect new vulnerabilities as developers open or update PRs, instead of after merge. * Gate merges based on security and compliance. * Enforce policies that can block risky PRs or fail CI builds. * Give developers fast feedback on open source, SAST, and secrets findings tied to their changes through PR comments and PR Runs in the Endor Labs UI. Endor Labs supports scanning pull requests and merge requests to evaluate the impact of proposed changes before they are merged. You can run PR scans in the following ways: * [Scan PRs using endorctl](#scan-prs-using-endorctl) to run pull request scans from the CLI. This approach supports scanning the pull request branch and scanning changes relative to a baseline branch. * [Configure PR scans in SCM apps](#configure-pr-scans-in-scm-apps) to trigger scans when a pull request or merge request is opened or updated. * [Configure PR scans in CI pipelines](#run-pr-scans-from-ci) to invoke endorctl as part of a CI pipeline in the pull request or merge request context. ## Pull request scan workflow The following workflow describes a robust approach for scanning pull requests and merge requests against a stable baseline branch. 1. **Establish and maintain a baseline branch** Scan your baseline branch, such as main, regularly with monitoring scans or CI scans. See [Set a default branch](/scan/sca/scanning-strategies#set-a-default-branch) for how the default branch is chosen and used. See [Scanning strategies](/scan/sca/scanning-strategies) and [Branches and workflows](/best-practices/operational-best-practices) for more information on branch strategy, default branch setup, and recommended scan flags. 2. **Trigger PR scans on feature branches** Configure PR scans for PRs targeting the baseline branch, for example, `main`. For large monorepos, enable incremental PR scans to focus only on changed dependencies and code. 3. **Use policies to enforce standards** Use finding and action policies to decide when to warn, break builds, or block merges for PR scans. 4. **Integrate first-party scans** Optionally, for app-triggered scans, enable SAST and secrets in the SCM integration when you install or manage the app. For CI-triggered scans, include the appropriate endorctl flags and steps in your pipeline so each run covers dependencies, first-party code, and secrets as needed. To analyze first-party code changes with AI SAST on pull requests, see [AI SAST PR scans](/scan/ai-sast/ai-sast-pr-scans). The following diagram shows how a pull request scan flows from the baseline to the merge decision. ## Scan PRs using endorctl You can scan pull requests or merge requests using endorctl for GitHub, GitLab, and Bitbucket. The `--pr` flag runs the scan for the current commit and records the results as PR Runs that do not affect main branch monitoring scans and reports. Endor Labs stores PR and MR scan findings in PR Runs for three weeks, after which they are removed to accommodate new PR scans. Before you run PR scans, scan your baseline branch at least once so incremental PR scans have a baseline to compare against. A PR scan command combines the following flags. The following sections explain how these flags work together. To go straight to the ready-to-run command, see [Set up PR scans step by step](#set-up-pr-scans-step-by-step). ## Perform incremental PR scan An incremental PR scan scans only the parts of the codebase and dependencies that have changed since the last full baseline scan. * Endor Labs identifies packages and dependencies in the PR and scans only those that changed relative to the baseline. * If no dependencies changed, the scan is skipped, and Endor Labs reports `No changes found`. * Incremental PR scans only report findings that do not exist in the baseline and are associated with changed dependencies in the PR. * You can enable incremental PR scans using the `--pr-incremental` flag or the equivalent CI settings. This flag is also available for [SAST incremental scans](/scan/sast#sast-incremental-scans) and [Incremental secret scans](/scan/secrets#incremental-secret-scans). You need to set a baseline for incremental PR scans so only findings new relative to that branch are reported. For GitHub App or GitLab App scans, or when PR comments are enabled, the baseline is detected automatically. Otherwise, pass `--pr-baseline` when you run the scan. See [Set a default branch](/scan/sca/scanning-strategies#set-a-default-branch) for how the default branch is chosen and used. **Baseline mismatch in PR scans** If a finding is fixed in the baseline by upgrading or downgrading a dependency and a PR still modifies that package, the finding can be reported as new. To mitigate this, rebase the PR with the latest baseline content and re-run the PR check. ### Publish findings as PR comments Endor Labs can post new findings as review comments on the pull request or merge request. Comments are posted according to your action policies. To publish comments: * Set `--enable-pr-comments` and `--scm-pr-id` so the scan posts comments to the right PR and infers the baseline from its merge target. * Authenticate with `--scm-token` or the `ENDOR_SCAN_SCM_TOKEN` environment variable. * Configure an action policy with Branch Type **Pull Request** so violations generate comments. See [Pull Request comments](/scan/pr-scans/pr-comments) for app-based setup, the required action policy configuration, and comment templates. ### Skip unaffected languages during incremental PR scans When you combine `--pr-incremental` with `--quick-scan`, Endor Labs inspects the changed files in the pull request before resolving dependencies for each language. If the pull request contains no build file changes for a language, Endor Labs skips dependency resolution for that language entirely. This behavior is enabled by default for all supported languages and ecosystems in endorctl v1.7.1002 and later. The scan log records each skipped language. ```text theme={null} Skip Java dependency resolution: No relevant changes detected ``` ### Skip unaffected packages during incremental PR scans When a pull request does change build files, Endor Labs can prune further and resolve dependencies only for the packages those files affect. This reduces incremental PR scan times in large repositories and monorepos. Endor Labs classifies each changed build file by its scope of impact: * A single package, such as `gradle.lockfile`. * A package and every package under it, such as a parent `pom.xml`, `settings.gradle`, or `gradle.properties`. * The entire repository, such as `gradle-wrapper.properties`, files under `buildSrc` or `.mvn`, and version catalogs like `gradle/libs.versions.toml`. Packages that no changed file affects are not resolved again, and their results carry forward from the baseline scan. Package-level skipping is enabled by default for Java and Kotlin projects that build with Maven or Gradle, in endorctl v1.7.1046 and later. It is enabled by default for JavaScript projects in endorctl v1.7.1063 and later. Support for more ecosystems is rolling out in upcoming releases. To turn off package-level skipping, set `ENDOR_SCAN_INCREMENTAL_DEP_RES=false` before you run the scan. ### Troubleshoot incremental PR scan performance If an incremental PR scan takes longer than expected or does not skip dependency resolution, do the following checks: 1. Verify that endorctl is v1.7.1002 or later. Package-level skipping requires v1.7.1046 or later for Java and Kotlin, and v1.7.1063 or later for JavaScript. 2. Confirm that the scan sets both `--pr-incremental` and `--quick-scan`. 3. Confirm that the scan is a pull request scan. Scans tagged `merge-to-main` resolve all dependencies. 4. Check the scan log for `Detected N changed files`. An unexpectedly large count means the pull request diff could not be computed correctly. 5. Look for skip confirmations in the scan log, such as `Skip dependency resolution for 3/12 maven modules: No relevant changes detected`. 6. Check whether the pull request changes a root or parent build file. These changes affect every module in the repository, so Endor Labs resolves all of them even with package-level skipping turned on. ### Maven dependency resolution on large projects Maven dependency resolution can take a long time on projects with large or complex dependency trees, when a PR changes a root or parent build file. To reduce dependency resolution time in PR scans: * Confirm that `--pr-incremental` and `--quick-scan` are both set. Endor Labs skips dependency resolution for languages and packages that a pull request does not affect. See [Skip unaffected packages during incremental PR scans](#skip-unaffected-packages-during-incremental-pr-scans). * For monorepos with 100 or more `pom.xml` files, set `ENDOR_SCAN_MAVEN_PREPOP_CACHE=true` in GitHub App or other hosted scans to pre-populate the Maven local cache in parallel before Endor Labs scans each module. This setting has no effect in CI-triggered or local `endorctl scan` runs. See [Environment variables that affect scan behavior](/developers-api/cli/environment-variables#environment-variables-that-affect-scan-behavior). ## Configure PR scans in SCM apps The Endor Labs SCM integrations let you scan pull requests or merge requests when they are opened or updated. In the integration settings, enable PR or MR scans to run them automatically and, optionally, enable pull request comments to post findings as review comments. Action policies apply to PR scans the same way as to other scan types. The following describe platform-specific setup and configuration options: * [Endor Labs GitHub App PR scans](/setup-deployment/scm-integrations/github-app/github-app#configure-pr-scans-during-github-app-pro-installation) * [GitLab App MR scans](/setup-deployment/scm-integrations/gitlab-app/gitlab-mr-scan) * [Bitbucket Cloud App](/setup-deployment/scm-integrations/bitbucket-cloud/bitbucket-cloud-pr-scans) * [Bitbucket Data Center App](/setup-deployment/scm-integrations/bitbucket-datacenter-app/bitbucket-datacenter-pr-scans) * [Azure DevOps App](/setup-deployment/scm-integrations/azure-app/azure-pr-scans) ## Run PR scans from CI PR scans can be run from a continuous integration pipeline by invoking `endorctl scan` with pull request flags in jobs triggered by pull request or merge request events. This approach provides control over when scans run, supports posting findings as PR or MR comments, and allows policies to be enforced, such as failing builds or blocking merges. The scan profile assigned to the project determines the toolchains and environment used for the scan. * See [CI scans](/setup-deployment/ci-cd) for platform-specific pipeline configuration. * See [Pull request flags](/developers-api/cli/commands/scan#pull-request-ci-flags) for available flags. ## Block pull requests on findings A PR scan reports findings, but it does not block a merge on its own. To gate a pull request, ensure that you have the following configurations: * An action policy that breaks the build when the findings you care about appear. * A required status check in your source control manager that enforces the result before a merge. The action policy decides which findings block a pull request, and the required status check is what stops the merge. ### Create an action policy that breaks the build In Endor Labs, create an action policy and choose the **Break the Build** enforcement action. Select the policy template for the finding types you want to gate, such as SCA, secrets, or SAST. The policy applies to PR scans the same way it applies to other scans. See [Create an action policy from template](/platform-administration/policies/action-policies#create-an-action-policy-from-template) for the full procedure. ### Configure the required status check in GitHub to block merges GitHub blocks a merge only when the Endor Labs check is a required status check on the target branch. The check you require depends on how Endor Labs scans your pull requests. The check appears as a selectable option only after it has reported on a pull request within the last seven days. Open or update a pull request so the Endor Labs check runs once, then add it to your branch protection rule. To add the check to a branch protection rule: 1. In your GitHub repository, select **Settings** > **Branches**. 2. Next to the rule for your default branch, click **Edit**. 3. Select **Require status checks to pass before merging**. 4. Enter the check name (**Endor Labs Automated Scan** for the GitHub App, or your workflow job name for GitHub Actions), and select it from the results. 5. Click **Save changes**. To create a rule instead, click **Add branch protection rule**, enter a **Branch name pattern**, and follow the same steps. GitHub also supports requiring status checks through repository and organization rulesets, which GitHub now recommends. Use an organization ruleset to enforce the check across many repositories at once. For more information, refer to [About rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). After you require the check, GitHub keeps the merge blocked until the check passes. A check that concludes as neutral or skipped does not block the merge, even when it is required. Endor Labs reports a neutral result when there is nothing to scan, such as a pull request with no relevant changes. For more information, see [Managing a branch protection rule](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule) and [About rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), and [Troubleshooting required status checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks) in the GitHub documentation. ### Configure the required status check in Azure DevOps to block merges To block pull requests from merging, configure a branch policy that requires the Endor Labs pull request status. The merge is blocked until the status succeeds. The Azure DevOps App posts this status as **endorlabs/Endor Labs Automated Scan**, which is what you select when you create the branch policy. You can select the status only after Endor Labs posts it to a pull request at least once. Open or update a pull request to let the scan run, and then add the branch policy. You can also enter **Genre** and **Name** manually before the first scan. To require the status on your default branch: 1. In Azure DevOps, select **Project settings** > **Repositories**. 2. Search for and select your repository. 3. Select **Policies**. 4. Under **Branch Policies**, select your default branch, such as `main`. 5. Next to **Status checks**, click **+**. 6. Select **endorlabs/Endor Labs Automated Scan** as the status to check. 7. Set **Policy requirement** to **Required**. 8. Optionally, set **Authorized identity** to the account that the Azure DevOps App authenticates with. Only statuses posted by that account satisfy the policy. 9. Under **Reset conditions**, clear **Reset status whenever there are new changes**. Endor Labs binds each status to the pull request iteration it scanned, so the reset keeps the merge blocked until the latest scan succeeds. 10. Click **Save**. The status fails when a finding matches an action policy set to **Break the Build**, and also when the scan itself fails to complete. Findings that match a **Warn** action policy still generate pull request comments, but the merge is not blocked. A **Not Applicable** status does not block a merge, even if the **Policy requirement** is set to **Required**. Endor Labs reports this status when the base branch of the pull request has not yet been scanned, or when the scan could not be performed. For more information, refer to [Configure a branch policy for an external service](https://learn.microsoft.com/en-us/azure/devops/repos/git/pr-status-policy) and [Iteration status](https://learn.microsoft.com/en-us/azure/devops/repos/git/pull-request-status#iteration-status). ### Block merges for PR scans run from Azure Pipelines When you run `endorctl` in an Azure Pipelines job instead of using the Azure DevOps App, Endor Labs does not post a pull request status. If a finding matches an action policy set to **Break the Build**, `endorctl` exits with [code 128](/best-practices/troubleshooting/endorctl-exitcodes), causing the pipeline job to fail. See [Scanning in Azure Pipelines](/setup-deployment/ci-cd/scan-with-azuredevops) to learn how to configure the pipeline. To block merges based on findings, configure a build validation policy for the pipeline that runs the Endor Labs scan. The merge remains blocked until the pipeline job succeeds. To require the pipeline on your default branch: 1. In Azure DevOps, select **Project settings** > **Repositories**. 2. Search for and select your repository. 3. Select **Policies**. 4. Under **Branch Policies**, select your default branch, such as `main`. 5. Next to **Build validation**, click **+**. 6. Select the **Build pipeline** that runs the Endor Labs scan. 7. Under **Trigger**, choose **Automatic (whenever the source branch is updated)**. 8. Set **Policy requirement** to **Required**. 9. Click **Save**. For more information, refer to [Set build validation](https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies#set-build-validation). ## Ignore files in PR scans Ignore files let you dismiss findings by committing a file in your repository as part of a pull or merge request. During a PR scan, Endor Labs applies the ignore file from the repository version being scanned. Findings that match entries in the ignore file are excluded from PR Runs, do not appear in [Pull Request comments](#pull-request-comments), and do not trigger action policies. **Tenant setting required for ignore files** You must [allow ignore files to dismiss findings](/platform-administration/configure-system-settings#allow-ignore-files-to-dismiss-findings) in **Settings** > **SYSTEM SETTINGS** > **Developer Workflows** for scans to process ignore files. To add or update entries, use [`endorctl ignore`](/developers-api/cli/commands/ignore) and validate the file with [`endorctl validate ignore`](/developers-api/cli/commands/validate/ignore). See [Dismiss findings using an ignore file](/inventory-insights/findings#dismiss-using-an-ignore-file) for more details on ignore file format and structure. ## Scan profiles for PR scans A scan profile defines the configuration applied to PR scans for a project, including languages, toolchains, path filters, and parameters such as `enable_automated_pr_scans` and `enable_pr_comments`. For CI-initiated PR scans, the scan profile determines the toolchains and environment configuration used to execute the scan. App-triggered PR scans run only when both of the following are true. * Pull Request scans or Merge Request scans are enabled during SCM app installation so the app receives PR or MR events. * **Pull request scans** or `enable_automated_pr_scans` is enabled in the scan profile assigned to the project. To scope app-triggered PR scans to selected projects, enable **Pull request scans** only in the scan profiles assigned to those projects. In GitLab, MR scans can alternatively be scoped by configuring merge request webhooks for selected projects. See [Configure scan profile through the UI](/scan/scan-profiles/configure-scanprofile-ui#configure-general-scan-profile-settings) for more information on scan profile settings. ## Pull Request comments PR comments are automated comments posted on pull or merge requests when Endor Labs detects policy violations during a PR scan. Enable them in your SCM integration or using `--enable-pr-comments` in CI, then configure an action policy with Branch Type **Pull Request**. See [Pull Request comments](/scan/pr-scans/pr-comments) and [Action policies](/platform-administration/policies/action-policies) for setup and configuration. ## Set up PR scans step by step Add the following flags to your scan command in order, and verify each step in your CI pipeline before adding the next. Run a PR scan on the current commit. Endor Labs records the results as a PR Run instead of a monitoring scan. ```bash theme={null} endorctl scan --namespace --pr ``` Add `--pr-incremental` and point `--pr-baseline` at the branch the PR merges into. The scan reports only findings that are new relative to the baseline. ```bash theme={null} endorctl scan --namespace --pr --pr-incremental --pr-baseline=main ``` Add `--quick-scan` to skip call graph generation and skip dependency resolution for languages and packages the PR does not affect. ```bash theme={null} endorctl scan --namespace --pr --pr-incremental --pr-baseline=main --quick-scan ``` Add `--enable-pr-comments` with `--scm-pr-id` and an SCM token. Remove `--pr-baseline` because the scan now infers the baseline from the merge target of the PR. This is the recommended command. ```bash theme={null} export ENDOR_SCAN_SCM_TOKEN= endorctl scan --namespace --pr --pr-incremental --quick-scan \ --scm-pr-id --enable-pr-comments ``` The scan reports findings and posts comments, but it does not block merges on its own. Pair the command with an action policy that breaks the build and a required status check on your target branch. See [Block pull requests on findings](#block-pull-requests-on-findings). If your organization runs GitHub Enterprise Server, add `--github-api-url` with the API URL of your server. ```bash theme={null} endorctl scan --namespace --pr --pr-incremental --quick-scan \ --scm-pr-id --enable-pr-comments --github-api-url= ``` ### Adjust the command for your setup * **Run without PR comments**: Stop after step 3. Keep `--pr-baseline` and do not set `--enable-pr-comments` or `--scm-pr-id`. * **Include reachability analysis**: Drop `--quick-scan` to resolve dependencies fully and generate call graphs. The scan takes longer, but findings include reachability information. ## View PR scan findings PR scan findings are stored as **PR Runs** and kept for three weeks to accommodate new PR activity. To view PR scan results in the Endor Labs: 1. Select **Projects** from the left sidebar. 2. Search for and select your project from the list. 3. Select **PR RUNS** to review the past scans. **PR Runs** captures the commit ID, **Commit SHA**, the referenced branch, its findings, and the tags added to the scan as configured in the policies. Select the specific PR scan to view its findings in detail. You can view the scan metadata, severity summary, and open any scan for findings, issues, and logs. PR scan results in PR Runs ## FAQs Endor Labs retains PR scan findings as PR Runs for three weeks. Endor Labs reports a finding as new if the baseline includes a fix for the issue and the pull request modifies the affected package. To resolve the finding, rebase the pull request on the latest baseline and re-run the PR scan. Results can differ when the PR or baseline branch changes, the scan profile is updated, or the vulnerability database is updated between runs. PR Runs store the findings produced at the time of execution. Subsequent PR scans evaluate the pull request using the current scan profile and the latest analysis data. No, PR scans do not block merges by default. Blocking requires an action policy that breaks the build and a required status check that enforces the result. See [Block pull requests on findings](#block-pull-requests-on-findings) for the steps. Endor Labs falls back to a full PR scan when no valid baseline exists for the project or when it cannot determine what changed relative to the baseline. Ensure the baseline branch has been scanned at least once before relying on incremental scans. See [Troubleshoot incremental PR scan performance](#troubleshoot-incremental-pr-scan-performance) for more checks. # Pull Request comments Source: https://docs.endorlabs.com/scan/pr-scans/pr-comments/index Learn how to enable and configure automated PR comments. PR comments are automated comments added to pull requests when Endor Labs detects policy violations or security issues during scans. When a PR is raised or updated, Endor Labs runs scans on the proposed changes and adds a comment if any violations are detected based on the configured action policies. ## Types of PR comments Endor Labs generates the following types of PR comments based on the nature of the findings in a scan: * **PR comments for Secrets**: For findings of type `FINDING_CATEGORY_SECRETS`, Endor Labs adds a comment directly on the specific line where the secret is detected, using the line number provided in the finding object. These comments remain visible even if the secret is removed in a later scan. * **PR comments for SCA**: For SCA findings, Endor Labs adds a single comment that applies to the entire PR. It summarizes all findings from the policy evaluation results. The comment is updated with each scan run to reflect only the latest findings. * **PR comments for SAST**: For findings of type `FINDING_CATEGORY_SAST`, Endor Labs adds a single comment that applies to the entire PR. It summarizes all SAST-related policy violations detected during the scan. The comment is updated with each run and reflects only the latest findings. ## Enable PR comments After enabling PR comments, you must [Configure an action policy](#configure-action-policy-for-pr-comments) to allow comments to be posted on pull requests or merge requests. ### GitHub PR comments You can enable PR comments for GitHub through one of the following methods. #### GitHub App You can enable PR comments during the initial setup of the [GitHub App (Pro)](/setup-deployment/scm-integrations/github-app), or by editing an existing integration. Once enabled, Endor Labs automatically adds comments to pull requests when policy violations are detected. #### GitHub Actions You can configure GitHub Actions to comment on PRs if there are any policy violations. Make sure that your GitHub Actions workflow includes the following configuration. * The workflow must have a `with` clause including: `enable_pr_comments` to `true` to publish new findings as review comments and `github_token: ${{ secrets.GITHUB_TOKEN }}`. This token is automatically provisioned by GitHub when using GitHub Actions. See [GitHub configuration parameters](/setup-deployment/ci-cd/scan-with-github-actions#endor-labs-github-action-configuration-parameters) for more information. * To grant Endor Labs the ability to comment on PRs you must include the permission `pull-requests: write`. The following example configuration comments on PRs if a policy violation is detected. The examples pin the Endor Labs GitHub Action to release `v1.1.12`. To use a newer release, copy the **Use in your workflow** reference from **Latest GitHub Action Release** in [Secure GitHub Actions with immutable commit SHA](/setup-deployment/ci-cd/scan-with-github-actions#secure-github-actions-with-immutable-commit-sha). ```yaml theme={null} - name: Endor Labs Scan PR to Default Branch if: github.event_name == 'pull_request' uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' # Update with your Endor Labs namespace scan_summary_output_type: 'table' scan_dependencies: true scan_secrets: true pr: true enable_pr_comments: true github_token: ${{ secrets.GITHUB_TOKEN }} ``` ##### PR comments example The [main.yaml](https://github.com/endorlabs/hearts-github/blob/main/.github/workflows/main.yml) file in this [sample repository](https://github.com/endorlabs/hearts-github) contains the following configuration to enable PR comments. ```yaml expandable theme={null} name: Build Release on: pull_request: branches: [main] workflow_dispatch: push: branches: [main] schedule: - cron: "23 23 * * 0" jobs: build: permissions: pull-requests: write security-events: write contents: read id-token: write actions: read runs-on: ubuntu-latest env: ENDOR_NAMESPACE: "endorlabs-hearts-github" steps: - name: Endor Labs Scan PR to Default Branch if: github.event_name == 'pull_request' uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: ${{ env.ENDOR_NAMESPACE }} pr: true enable_pr_comments: true github_token: ${{ secrets.GITHUB_TOKEN }} ``` The [PR #10](https://github.com/endorlabs/hearts-github/pull/10) introduced a reachable vulnerability. Since the workflow has `enable_pr_comments` set as `true`, a comment is added to the PR on the policy violation. You can expand the comment to view the following details: * Issue type: Describes the category of the security or policy violation * Severity: Indicates how critical the issue is. * Impacted files or dependencies: Specifies the files and packages affected by the issue. * Remediation steps: Specifies the required fix to resolve the detected issue. PR Comment Details #### GitHub PR comments with Endor Labs CLI You can generate PR comments using the CLI by including the following flags in the `endorctl scan` command. ```bash theme={null} endorctl scan \ --pr \ --enable-pr-comments \ --scm-token \ --scm-pr-id \ --namespace ``` Ensure that you set the following parameters: * Set `--enable-pr-comments` to activate PR comment generation. * Use `--scm-pr-id` to specify the pull request to comment on. * Use `--scm-token` (or set the `ENDOR_SCAN_SCM_TOKEN` environment variable) and set the `pull-requests` permission to `write` for the token. To speed up the scan, also set `--pr-incremental` and `--quick-scan`. See [Set up PR scans step by step](/scan/pr-scans#set-up-pr-scans-step-by-step) for the complete command. You can continue to use `--github-pr-id` flag, but it will be deprecated and removed in the future. ### GitLab MR comments You can enable MR comments for GitLab through one of the following methods. #### GitLab App You can enable MR comments during the initial setup of the [GitLab App](/setup-deployment/scm-integrations/gitlab-app) or by editing an existing integration. Once enabled, Endor Labs automatically adds comments to merge requests when policy violations are detected. See [GitLab MR comments](/setup-deployment/scm-integrations/gitlab-app/gitlab-mr-scan#gitlab-mr-comments) for more information. #### GitLab CI pipelines You can configure GitLab CI pipelines to comment on merge requests when policy violations are detected. Add `--enable-pr-comments`, `--scm-pr-id=$CI_MERGE_REQUEST_IID`, and `--scm-token=$ENDOR_SCAN_SCM_TOKEN` to your scan command. Configure a GitLab CI/CD variable `ENDOR_SCAN_SCM_TOKEN` with your GitLab personal access token with the `api` scope. See [Enable MR comments](/setup-deployment/ci-cd/scan-with-gitlab#enable-mr-comments) for complete configuration examples. #### GitLab MR comments with endorctl You can generate MR comments with endorctl by including the following flags in the `endorctl scan` command. ```bash theme={null} endorctl scan \ --pr \ --enable-pr-comments \ --scm-token \ --scm-pr-id \ --namespace ``` Ensure that you set the following parameters: * Set `--enable-pr-comments` to activate MR comment generation. * Use `--scm-pr-id` to specify the merge request to comment on. * Use `--scm-token`. The token takes priority over installation PATs. To speed up the scan, also set `--pr-incremental` and `--quick-scan`. See [Set up PR scans step by step](/scan/pr-scans#set-up-pr-scans-step-by-step) for the complete command. Security review comments for GitLab merge requests are not yet supported. ## Configure Action policy for PR comments You must create an Action policy to receive comments on your pull request after enabling PR comments. 1. Create an [Action policy](/platform-administration/policies/action-policies). 2. Set the **Branch Type** to `Pull Request` so the policy applies specifically to pull request scans. 3. Under **Action**, select **Enforce Policy**, then choose: * **Warn** to post a comment without breaking the build. * **Break the Build** to fail the build and block the pull request. 4. Define the scope of the policy using tags. Only projects that match the specified tags will receive PR comments. ## Customize PR comments templates Endor Labs provides a default template with standard information that will be included in your pull requests as comments. You can use the default template, or you can choose to edit and customize this template to fit your organization's specific requirements. You can also create custom templates using [Go Templates](https://pkg.go.dev/text/template). 1. Select **User menu** > **Integrations** from the left sidebar. 2. Click **Edit Template** next to **GitHub PR comments** under **Notifications**. 3. Make the required changes and click **Save Template**. ### PR comments data model To create custom templates for PR comments, you must understand the data supplied to the template. See the following protobuf specification for the `GithubCommentData` message that this template uses. See the following sections to understand the Finding and PackageVersion definitions that are used in this protobuf specification: * [Finding resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#finding) * [PackageVersion resource kind](/developers-api/rest-api/using-the-rest-api/data-model/resource-kinds#packageversion) See the following specification to understand the additional functions that are also available. You can access these functions by using their corresponding keys. # RSPM (Repository Security Posture Management) Source: https://docs.endorlabs.com/scan/rspm/index Manage repository security posture and SCM configurations. Repository Security Posture Management (RSPM) helps you secure critical components of your software supply chain, including code, open source libraries, and repository configurations to ensure the security posture of your software development environment. ## Key capabilities * **Out-of-the-box policies**: Endor Labs comes with out-of-the-box finding policies that help you detect misconfigurations, enforce coding best practices, and stay compliant with industry standards such as CIS benchmarks for GitHub and more. * **Regular updates**: Endor Labs regularly updates its existing policies and includes new policies. Configure policy settings to ensure that you benefit from these regular updates. * **Remediation guidance**: The policies provide up-to-date insights into critical risks, so you can manage security threats before your projects even start. They also include remediation advice that can help you fix and mitigate issues. ## Supported platforms RSPM is currently supported for: | Platform | Support | | ------------------------ | ------- | | GitHub Cloud | Yes | | GitHub Enterprise Server | Yes | | Azure DevOps | No | | GitLab | No | | Bitbucket | No | ## Getting started 1. Review the available [finding RSPM policy templates](/platform-administration/policies/finding-policies/managing-scm-configuration). 2. [Configure policy settings](/platform-administration/configure-system-settings) to enable automatic updates. 3. Review findings in the and take corrective action. # Create Exception Policy for SAST Findings Source: https://docs.endorlabs.com/scan/sast/create-exception-policy/index Exception policies define the conditions for applying an exception to a finding. When an exception is applied to a finding, it is tracked as an exception and action policies do not apply to it. Findings with exceptions are filtered out from Endor Labs reports by default. See [Exception Policies](/platform-administration/policies/exception-policies) for more information. Instead of creating an exception policy, you can also use the following methods to avoid findings: * Disable the rule under SAST Rules * Use the `include-path` and `exclude-path` to scan parts of the project You can create an exception policy so that you can mark a SAST finding as an exception. For example, you want to mark findings with the description, `Detected Potential Open Redirect Vulnerability in Angular Application`, as exceptions. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Exception Policies**. 3. Click **Create Exception Policy** to create a new exception policy. 4. Select **SAST** as the **Template Category**. 5. Select **SAST** as the **Policy Template**. 6. Select from the following reasons why you are applying this exception: * **In Triage**: The finding is still being triaged for more information. * **False Positive**: The finding is a false positive. * **Risk Accepted**: The risk associated with the finding is accepted. * **Resolved**: The issue has been resolved. * **Other**: Another reason applies for this exception. 7. Select when the exception should expire. Options include 30, 60, 90 days, and Never. 8. **Assign Scope** for which this exception policy should apply. Scopes are defined by the tags assigned to a project. * In **Inclusions**, enter the tags of the projects that you want to apply an exception to. * In **Exclusions**, enter the tags of the projects that you do not want to apply an exception to. Exclusions take precedence over the inclusions, in case of a conflict. * Click the link to view the projects included in the finding policy. See [Tagging projects](/platform-administration/policies/tagging-projects) for more information about creating project tags. 9. Enter a human-readable **Name** for your exception policy. 10. Enter a **Description** for your exception policy that explains its function. 11. Enter any **Policy Tags** that you want to associate with your policy. Tags can have a maximum of 255 characters and can contain letters, numbers, and characters = @ \_ - 12. Deselect **Propagate this policy to all child namespaces** to prevent the policy from being applied to any child namespace. 13. Click **Create Exception Policy**. ## Create exceptions from the findings You can also create exceptions directly from a finding. 1. Select **Projects** from the left sidebar. 2. Search for and select a project, and select **Findings**. 3. Search for findings using advanced or basic filters. 4. Select findings and click the vertical three dots. 5. Select **Add Exception Policy**. 6. Select a template or create the policy from scratch. The template parameters are automatically pre-filled based on the selected finding. 7. Click **Create Exception Policy**. Use this feature to specifically apply exception to findings with a specific hash value. For example, `Detected Potential time of check time of use vulnerability (open/fopen): ID #e81f27`. This exception policy after creation only applies to the SAST findings with this hash ID and not any others. # SAST (Static Application Security Testing) Source: https://docs.endorlabs.com/scan/sast/index Find security vulnerabilities in your first-party code with rule-based SAST or AI SAST. Static Application Security Testing (SAST) is an automated security analysis methodology that examines application code to identify potential security vulnerabilities without executing the code. SAST has the following characteristics: * White-box Testing: Provides full visibility into application internals * Non-runtime Analysis: Performs scans without code execution * Early Detection: Identifies vulnerabilities during development phases * Language Support: Analyzes multiple programming languages and frameworks Endor Labs offers two ways to run SAST scans on your first-party code: * [Rule-based SAST](/scan/sast/rule-based-sast): Pattern-based static analysis powered by Opengrep. Fast, deterministic scans that match your source code against a curated set of rules. * [AI SAST](/scan/ai-sast): LLM-powered agents that find vulnerabilities rule-based scans cannot express, and triage rule-based findings to cut false positives. - Enable the [default SAST finding policies](/platform-administration/policies/finding-policies/sast-policies) to generate findings from SAST scans. - Endor Labs does not scan the files included in the `.gitignore` files during a SAST scan. You can also use the `nosemgrep` annotation in the code to skip a SAST scan. Refer to the [Semgrep documentation](https://semgrep.dev/docs/ignoring-files-folders-code#ignore-code-through-nosemgrep) for more information. - You can create exception policies to exclude results from the findings page. See [create exception policy](/scan/sast/create-exception-policy) for more information. ## Rule-based SAST scans Endor Labs offers several ways to run rule-based SAST scans based on your project setup. * [SAST scan with endorctl](/scan/sast/run-a-sast-scan): Run a SAST scan from the command line using endorctl by adding the `--sast` flag. * SAST scan in monitoring scans: Enable SAST scans when you configure monitoring or supervisory scans using the Endor Labs SCM Apps. See [SCM Integrations](/setup-deployment/scm-integrations) for setup instructions. To disable code snippet storage in SAST scans for monitoring scans, [create a scan profile](/scan/scan-profiles/configure-scanprofile-ui) and configure the required settings. This setting applies to all scans that use this scan profile, not just the monitoring scans. * [SAST scan in Endor Labs GitHub Action](/setup-deployment/ci-cd/scan-with-github-actions): Enable SAST scan in the Endor Labs GitHub Action by setting the scanning parameter `scan_sast` as `true`. To disable code snippet storage for SAST scans, set `disable_code_snippet_storage` as `true`. ## AI SAST scans Endor Labs offers several ways to run AI SAST scans based on your project setup. * [AI SAST triage agent with endorctl](/scan/ai-sast/triage-agent): Run AI SAST triage agent scans using endorctl by adding the `--ai-sast-analysis=agent-fallback` flag to your scan command. The AI SAST triage agent automatically classifies findings as true positives or false positives, reducing manual triage effort. * [AI SAST detection agent with endorctl](/scan/ai-sast/detection-agent): Run AI SAST detection agent scans using endorctl to identify security vulnerabilities beyond traditional rule-based detection. The AI SAST detection agent generates new findings labeled with an `AI` tag. * [AI SAST scans in SCM apps](/scan/ai-sast#ai-sast-scans-in-scm-apps): Enable AI SAST scans in monitoring or supervisory scans. [Create a scan profile](/scan/scan-profiles/configure-scanprofile-ui) for the project and enable AI SAST in the scan profile. The setting applies to all scans that use this scan profile. * [AI SAST scans in Endor Labs GitHub Action](/setup-deployment/ci-cd/scan-with-github-actions): Run AI SAST scans in the Endor Labs GitHub Action by passing the relevant flag in `additional_args`. ## SAST incremental scans You can use the `--pr-incremental` flag to perform an [incremental scan](/scan/pr-scans#perform-incremental-pr-scan) on your pull requests or merge requests for SAST. In monitoring scans, incremental scans run by default for PR scans. Endor Labs only scans the files that have changed since the last scan on the baseline branch by computing a diff between the target branch and the baseline branch. Endor Labs identifies the changed files, scans any modified file fully for SAST issues, and skips the scan on unchanged files. Endor Labs does not perform chunk-level or line-level code diff analysis for SAST. If there are more than 1000 modified files, Endor Labs performs a complete scan. # Add metadata to a SAST rule Source: https://docs.endorlabs.com/scan/sast/manage-sast-rules/add-metadata-sast-rule/index You can add metadata to the custom SAST rule that you create or when you clone an existing Endor Labs rule in the metadata section. The following example shows the SAST rule template with the metadata section. ```yaml expandable theme={null} rules: - id: - languages: - < java | js | py > < patterns, mode, options > message: < Rule message that provides details about the matched pattern and informs about how to mitigate any related issues, and can be shown in the Endor Labs user interface. > severity: < INFO | WARNING | ERROR > metadata: version: 1.0.0 description: A customer visible description for this rule. explanation: | An explanation of the issue. remediation: | Possible remediation steps you can take to fix the issue. cwe: - "CWE-xxx: " likelihood: < HIGH | MEDIUM | LOW > impact: < HIGH | MEDIUM | LOW > confidence: < HIGH | MEDIUM | LOW > ``` You can add the following metadata information to the rule: * `explanation`: An explanation of the issue. * `remediation`: Possible remediation steps you can take to fix the issue. * `cwe`: The CWE ID of the issue. The OWASP or SANS-25 category of the CWE ID will automatically appear under **Rule Tags** in **Findings** if such a mapping can be established. The following image shows an example where the CWE-22 is automatically mapped to the appropriate category. Finding details * `impact`: The impact of the issue. Impact is one of the factors that determines the severity of the issue. See [SAST severity matrix](/scan/sast/rule-based-sast#sast-severity-matrix) for more information. * `confidence`: The confidence level that the issue is real. Confidence is one of the factors that determines the severity of the issue. See [SAST severity matrix](/scan/sast/rule-based-sast#sast-severity-matrix) for more information. For example: ```yaml theme={null} rules: - id: python_ssl_rule-ssl-no-version . . . metadata: explanation: | The application was found calling an SSL module with SSL or TLS protocols that have known deficiencies. It is strongly recommended that newer applications use TLS 1.2 or 1.3 and `SSLContext.wrap_socket`. remediation: | If using the `pyOpenSSL` module, please note that it has been deprecated and the Python Cryptographic Authority strongly suggests moving to use the [pyca/cryptography](https://github.com/pyca/cryptography) module instead. To remediate this issue for the `ssl` module, create a new TLS context and pass in `ssl.PROTOCOL_TLS_CLIENT` for clients or `ssl.PROTOCOL_TLS_SERVER` for servers to the `ssl.SSLContext(...)` `protocol=` argument. When converting the socket to a TLS socket, use the new `SSLContext.wrap_socket` method instead. . . . ``` When Endor Labs generates a finding based on this rule, the explanation and remediation sections appear in the finding details. Finding details The metadata information also appears in the SARIF output. ````json expandable theme={null} { "locations": [ { "physicalLocation": { "artifactLocation": { "uri": "samples/3p/gitlab/python/ssl/rule-ssl-with-bad-version.py" }, "region": { "startLine": 9 } } } ], "message": { "text": "Problem:\nThe application was found calling an SSL module with SSL or TLS protocols that have known deficiencies. It is strongly\nrecommended that newer applications use TLS 1.2 or 1.3 and `SSLContext.wrap_socket`.\n\nSolution:\nIf using the `pyOpenSSL` module, please note that it has been deprecated and the Python Cryptographic Authority strongly\nsuggests moving to use the [pyca/cryptography](https://github.com/pyca/cryptography) module instead.\nTo remediate this issue for the `ssl` module, create a new TLS context and pass in `ssl.PROTOCOL_TLS_CLIENT` for clients\nor `ssl.PROTOCOL_TLS_SERVER` for servers to the `ssl.SSLContext(...)` `protocol=` argument. When converting the socket\nto a TLS socket, use the new `SSLContext.wrap_socket` method instead.\n\nExample creating a TLS 1.3 client socket connection by using a newer version of Python (3.11.4) and the SSL module:\n```\nimport ssl\nimport socket\n\n# Create our initial socket\nwith socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:\n # Connect the socket\n sock.connect(('www.example.org', 443))\n\n # Create a new SSLContext with protocol set to ssl.PROTOCOL_TLS_CLIENT\n # This will auto-select the highest grade TLS protocol version (1.3)\n context = ssl.SSLContext(protocol=ssl.PROTOCOL_TLS_CLIENT)\n # Load our a certificates for server certificate authentication\n context.load_verify_locations('cert.pem')\n # Create our TLS socket, and validate the server hostname matches\n with context.wrap_socket(sock, server_hostname=\"www.example.org\") as tls_sock:\n # Send some bytes over the socket (HTTP request in this case)\\\n data = bytes('GET / HTTP/1.1\\r\\nHost: example.org\\r\\n\\r\\n', 'utf-8')\n sent_bytes = tls_sock.send(data)\n # Validate number of sent bytes\n # ...\n # Read the response\n resp = tls_sock.recv()\n # Work with the response\n # ...\n```\n\nFor more information on the ssl module see:\n- https://docs.python.org/3/library/ssl.html\n\nFor more information on pyca/cryptography and openssl see:\n- https://cryptography.io/en/latest/openssl/\n" }, "properties": { "explanation": "The application was found calling an SSL module with SSL or TLS protocols that have known deficiencies. It is strongly recommended that newer applications use TLS 1.2 or 1.3 and `SSLContext.wrap_socket`.\n", "remediation": "If using the `pyOpenSSL` module, please note that it has been deprecated and the Python Cryptographic Authority strongly suggests moving to use the [pyca/cryptography](https://github.com/pyca/cryptography) module instead. To remediate this issue for the `ssl` module, create a new TLS context and pass in `ssl.PROTOCOL_TLS_CLIENT` for clients or `ssl.PROTOCOL_TLS_SERVER` for servers to the `ssl.SSLContext(...)` `protocol=` argument. When converting the socket to a TLS socket, use the new `SSLContext.wrap_socket` method instead.\n", "tags": [ "A02:2021", "Cryptographic-Failures", "OWASP-Top-10" ] } } ```` # Clone a SAST rule Source: https://docs.endorlabs.com/scan/sast/manage-sast-rules/clone-sast-rule/index You can clone an existing SAST rule and use that as a base to build your own rule. Cloning a rule provides the following benefits: * You can make changes to a rule and review the results instead of directly editing an existing rule. * You can create a clone of a rule that you do not have permission to edit and make your changes. To clone a SAST rule: 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **SAST RULES**. 3. Click the vertical three dots next to a rule and select **Clone**. A copy of the rule appears in the list of rules with the rule name in the format, `-\`. For example, if you clone the rule `Arbitrary Code Execution - Unsanitized inputs` for the first time, a clone rule is created with the name, `Arbitrary Code Execution - Unsanitized inputs-1`. Clone SAST rule 4. Click edit to the cloned rule to edit the cloned rule according to your requirements. See [Edit a SAST rule](/scan/sast/manage-sast-rules/edit-a-sast-rule) for more information. # Create a SAST rule Source: https://docs.endorlabs.com/scan/sast/manage-sast-rules/create-sast-rule/index To create a SAST rule: 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **SAST RULES**. 3. Click **Create SAST Rule**. 4. Enter the SAST rule in the yaml format. Create SAST rule 5. Click **Save** to save the rule. # Edit a SAST rule Source: https://docs.endorlabs.com/scan/sast/manage-sast-rules/edit-a-sast-rule/index You can edit only the custom SAST rules. You cannot edit or delete Endor Labs or third-party rules. To edit a SAST rule: 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **SAST RULES**. 3. Click edit next to a rule and select **Edit Rule**. Edit SAST rule 4. After you complete the edits, click **Save** to save the rule. # Import SAST rules Source: https://docs.endorlabs.com/scan/sast/manage-sast-rules/import-sast-rule/index You can import Semgrep-compatible SAST rules that you create as yaml files. The files must have `yaml` or `yml` extensions and the rules should be inside a gzip or tar archive. ## Import SAST rules through the user interface You can bulk import rules through the user interface. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **SAST RULES**. 3. Click **Import**. Import SAST rule 4. Click **Browse** and select the archive file that contains the rules. 5. Enter the version of the rule, if required. If you do not enter a version and the rules already exist in the system, the rule upload may fail. ### Import SAST rules with endorctl You can bulk import a number of rules using the following command. ```bash theme={null} endorctl rule-set import --file-path --rule-version -n namespace ``` # SAST Rules Source: https://docs.endorlabs.com/scan/sast/manage-sast-rules/index Endor Labs uses Semgrep-compatible rules for SAST scans. Endor Labs includes hundreds of rules for multiple languages, including rules created by Endor Labs and vetted third-party rules. To this end, Endor Labs reviews existing open source rules and complements them with Endor Labs rules to cover additional technologies or vulnerability types. You can edit existing rules in your tenant to make modifications specific to your environment. You can also create new custom rules with the rule designer based on your requirements. You can also use the rule designer to add any Semgrep rule as a custom rule. From the left sidebar, navigate to **User menu** > **Policies & Rules** and select **SAST RULES** to view all SAST rules in the system. SAST rules You can use the toggle against a rule to enable or disable the rule during the scan. You can search for rules based on parameters such as rule name, languages, CWE, and tags. ## Rule Permissions You can create SAST rules in your tenants, and can edit, delete, or propagate them to child namespaces. But you cannot edit rules that are marked as Endor Labs or 3rd Party. You can choose to disable the rule to not apply them during scanning or clone them to modify the rules. The following sections provide more information on the actions you can do with SAST rules. * [Create a SAST rule](/scan/sast/manage-sast-rules/create-sast-rule) * [Edit a SAST rule](/scan/sast/manage-sast-rules/edit-a-sast-rule) * [Clone a SAST rule](/scan/sast/manage-sast-rules/clone-sast-rule) * [Import a SAST rule](/scan/sast/manage-sast-rules/import-sast-rule) * [Add metadata to a SAST rule](/scan/sast/manage-sast-rules/add-metadata-sast-rule) # Rule-based SAST Source: https://docs.endorlabs.com/scan/sast/rule-based-sast/index Run rule-based static analysis on your first-party code using Opengrep. Rule-based SAST in Endor Labs uses [Opengrep](https://www.opengrep.dev/) to scan your source code against a curated set of pattern-based rules. Scans are fast and deterministic and run without executing the code. The [AI SAST triage agent](/scan/ai-sast/triage-agent) runs on top of rule-based SAST to automatically classify each finding as a true positive or false positive, cutting the manual triage effort that rule-based scans typically require. ## How rule-based SAST works Opengrep is an open-source, static analysis tool that finds bugs and vulnerabilities in source code using pattern matching. Opengrep parses the source code, applies pattern matching based on rules, and reports matches based on the rule specifications. Opengrep rules are in the YAML format. When you run a SAST scan, Endor Labs downloads Opengrep and works seamlessly. If you wish, you can use Semgrep instead of Opengrep with Endor Labs. If you use Semgrep with Endor Labs, SAST scan is supported on macOS and Linux, and not supported on Windows. Endor Labs includes a set of [curated rules](/scan/sast/manage-sast-rules). You can [create your own rules](/scan/sast/manage-sast-rules/create-sast-rule) or [import rules](/scan/sast/manage-sast-rules/import-sast-rule) with the rule designer. Enable the [default SAST finding policies](/platform-administration/policies/finding-policies/sast-policies) to generate findings from SAST scans. When you [scan with the SAST option enabled](/scan/sast/run-a-sast-scan), Endor Labs uses Opengrep to scan for weaknesses in your source code based on SAST rules and generates findings based on the configured finding policies. Endor Labs does not scan the files included in the `.gitignore` files during SAST scan. You can also use the `nosemgrep` annotation in the code to skip SAST scan. Refer to the [Semgrep Documentation](https://semgrep.dev/docs/ignoring-files-folders-code#ignore-code-through-nosemgrep) for more information. Login to [Endor Labs](https://app.endorlabs.com/login) to view the findings of a SAST scan. See [View SAST findings](/scan/sast/viewing-sast-findings) for more information. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. You can create exception policies to exclude results from the findings page. See [create exception policy](/scan/sast/create-exception-policy) for more information. You can create a finding policy using predefined templates to control which SAST results appear as findings. See [SAST policies](/platform-administration/policies/finding-policies/sast-policies) for more information. ## SAST severity matrix Endor Labs determines the severity of findings by combining two factors from the SAST rule: impact and confidence. Impact measures the potential consequences of exploiting a security issue. Confidence represents the certainty that a detected pattern is a genuine security issue rather than a false positive. If either factor cannot be determined, the severity defaults to low. The following matrix shows how Endor Labs resolves severity by combining impact and confidence.
High Impact Medium High Critical
Medium Impact Low Medium High
Low Impact Low Low Medium
Low Confidence Medium Confidence High Confidence
For ways to run a SAST scan, and incremental scan behavior, see [SAST overview](/scan/sast). ## Language support Endor Labs supports single-function analysis for the following languages through curated rules and custom user rules: ```shell expandable theme={null} - Apex - Bash - C - Cairo - Circom - Clojure - C++ - C# - Dart - Dockerfile - Elixir - Generic - Go - Hack - HTML - Java - JavaScript - JSON - Jsonnet - Julia - Kotlin - Lisp - Lua - Move - OCaml - PHP - PromQL - Protobuf - Python - QL - R - Regex - Ruby - Rust - Scala - Scheme - Solidity - Swift - Terraform - TypeScript - XML - YAML ``` # Run a SAST scan Source: https://docs.endorlabs.com/scan/sast/run-a-sast-scan/index Run SAST scans with endorctl to identify security vulnerabilities and code quality issues in your source code. Run a SAST scan with endorctl to identify security vulnerabilities and code quality issues in your source code. Ensure that you [install endorctl](/introduction/getting-started) and configure your environment to run Endor Labs scan before you proceed to do a SAST scan. ## SAST scan You can run a SAST scan on a project with endorctl using the following command. ```bash theme={null} endorctl scan --sast --path=/path/to/code -n ``` To view findings generated by this scan, see [view SAST findings](/scan/sast/viewing-sast-findings). ## SAST scan options You can run the `endorctl scan --sast` command with the following options. # View SAST Findings Source: https://docs.endorlabs.com/scan/sast/viewing-sast-findings/index View, filter, and export SAST findings in Endor Labs. You can view SAST findings in the Findings page. 1. Select **Findings** > **SAST** from the left sidebar. View SAST findings 2. You can use the filters to further refine the SAST findings. 3. Select a row to view finding details. View SAST finding details 4. Select **Rule** to view the rule that triggered the finding. View SAST finding rules 5. To export findings as a CSV file, select the findings, click the vertical three dots, and select **Export Selected** or **Export All**. See [export findings](/inventory-insights/findings#export-findings) to learn more. SAST finding export For findings generated by the AI SAST triage agent, see [View AI SAST triage agent findings](/scan/ai-sast/triage-agent#view-ai-sast-triage-agent-findings). For findings generated by the AI SAST detection agent, see [View AI SAST detection agent findings](/scan/ai-sast/detection-agent#view-ai-sast-detection-agent-findings). # Approximate scans Source: https://docs.endorlabs.com/scan/sca/approximate-scans/index Learn about approximate scans in Endor Labs Endor Labs performs an approximate scan in situations where dependency resolution is impossible. This can happen due to build errors or incomplete dependency information. In such cases, an approximate scan estimates dependencies based on the available, unresolved dependency data. Since an approximate scan relies on unresolved dependency information, it is not as accurate as a scan based on resolved dependency information. However, an approximate scan can still provide valuable insights and help you identify potential issues. ## How an approximate scan works The approximate scan looks at the unresolved dependency data and estimates the resolved version based on the information available. For example, if the version is pinned then the approximate scan uses that version. If the version is not specified, then it uses the latest version. The scan generates the findings based on these approximations. False positives can occur if the actual resolved version is different from the approximated version, or if multiple places include the same dependency. Endor Labs automatically performs an approximate scan if full dependency resolution fails. You cannot disable approximate scans, and you cannot initiate an approximate scan manually. Review the scan logs to identify the root cause of the dependency resolution failures that resulted in the approximate scan. See [Scan history](/inventory-insights/scan-history) for more information on investigating previous scans and dependency resolution errors. ## Ignore findings from approximate scans If you know the approximate scan is inaccurate and want to ignore the findings, add an [exception policy](/platform-administration/policies/exception-policies). See [create an exception policy from a template](/platform-administration/policies/exception-policies#create-an-exception-policy-from-a-template) for details on how to create an exception policy. When you create the exception policy, choose the following options: * Select **Custom** as the policy template when you **Define Exception Criteria**. * Select **Yes** for the **Approximate Dependency** option. You can refine the exception policy by adding more criteria like **Source Code Ecosystem** and **Dependency Scope**. See [exception policy templates](/platform-administration/policies/exception-policies/templates#custom-advanced) for more information on the fields you can use to refine the exception policy. Alternatively, you can create your own exception policy [from scratch](/platform-administration/policies/exception-policies#create-an-exception-policy-from-scratch). # Scan artifacts and binaries Source: https://docs.endorlabs.com/scan/sca/binary-artifact-scan/index Detect and manage software supply chain risks by scanning software binaries and artifacts using Endor Labs. You can now perform endorctl scan on your binaries and artifacts without requiring access to source code or build systems. Scan Java and Python packages that are pre-built, bundled, or downloaded into your local system by specifying a file path to your artifact or binary package. Endor Labs scans the specified package, producing vital scan artifacts such as details about resolved dependencies and transitive dependencies, along with comprehensive call graphs. It enables you to acquire valuable insights and improve the security and reliability of the software components. ## System specifications for deep scan Before you proceed to run a deep scan, ensure that your system meets the following specification. | Project Size | Processor | Memory | | ----------------- | ----------------- | ------ | | Small projects | 4-core processor | 16 GB | | Mid-size projects | 8-core processor | 32 GB | | Large projects | 16-core processor | 64 GB | ### File format specifications When scanning archive formats such as `.zip`, `tar`, and `.tar.gz`, we support embedded package formats including `.jar`, `.ear`, `.war`, and `.whl.` We also support `.tar.gz` archives that contain Python package metadata such as egg-info. You can scan JAR, WAR, and EAR package file formats built using Maven or Gradle with a `pom.xml` configuration file. To scan packages without a `pom.xml` configuration, see [Scan Java packages without pom.xml](/scan/sca/java#scan-projects-without-pomxml). ### Software prerequisites If you have a private registry and internal dependencies on other projects, you must configure private registries for the Python and Java projects. See [Configure package manager integrations](/integrations/package-managers) for more information. ## Understand the scan arguments Use `--package` as an argument to scan artifacts or binaries. You must provide the path of your file using `--path` and specify a name for your project using `--project-name`. ```bash theme={null} endorctl scan --package --path --project-name ``` ## Run the scan Use the following options to scan your repositories. ### Option 1 - Quick scan Perform a quick scan of the local packages to get quick visibility into your software composition. This scan won't perform reachability analysis to help you prioritize vulnerabilities. **Syntax**: ```bash theme={null} endorctl scan --quick-scan --package --path=<> --project-name=<> ``` **Example**: ```bash theme={null} endorctl scan --quick-scan --package --path=/Users/username/packages/logback-classic-1.4.10.jar --project-name=package-scan-for-java ``` ### Option 2 - Deep scan Use the deep scan to perform dependency resolution, reachability analysis, and generate call graphs. You can do this after you complete the quick scan successfully. **Syntax**: ```bash theme={null} endorctl scan --package --path=<> --project-name=<> ``` **Example**: ```bash theme={null} endorctl scan --package --path=/Users/username/packages/logback-classic-1.4.10.jar --project-name=java-package-scan ``` ## View results You can sign into the [Endor Labs user interface](https://app.endorlabs.com), click the **Projects** on the left sidebar, and find your project using the name you entered to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. You can view the list of projects created for scanning packages using the `Platform Source in: Binary` filter. Projects search results for package scans with Platform Source binary filter # C/C++ Source: https://docs.endorlabs.com/scan/sca/c/index Learn how to implement Endor Labs in C and C++ repositories. C and C++ are powerful, high-performance programming languages widely used for system programming, application development, and embedded systems. Endor Labs supports scanning and monitoring of C and C++ projects. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## Run a scan To scan your C and C++ repositories, run the following command. ```bash theme={null} endorctl scan --segment-match-languages=c ``` **Important** * Ensure that the entire source code and all its dependencies are present in the scanned folder. * sing the `--segment-match-languages=c` flag will scan only C and C++ projects. For a multi-language repository, ensure that you include all other languages with the `--languages` flag. * If you are using a [scan profile](/scan/scan-profiles/configure-scanprofile-ui), make sure **C/C++** is selected under **Languages** and included in your profile. Use the following flags to save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan --segment-match-languages=c -o json | tee /path/to/results.json ``` ### View scan results You can sign in to the [Endor Labs user interface](https://app.endorlabs.com), click the **Projects** on the left sidebar, and find your project to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. View scan results ## View dependency file locations You can view a visualization of dependency file locations of C/C++ packages in your repository. These locations reflect the source file paths associated with how the dependency was identified in your codebase. To view the dependency file path of your package version: 1. Select **Projects** from the left sidebar. 2. Go to **Packages** under **Inventory**. 3. Select **C/C++** in the **Ecosystem** filter. 4. Select the package version you want to review. 5. Click **View Details** on the right sidebar. 6. Select **Overview**. 7. Expand the tree under **Dependency File Locations** to explore the file paths where the dependency was identified. Dependency file locations tree under Overview ## Understand the scan process Endor Labs detects vulnerabilities by testing your code against its proprietary database, which is regularly updated. Endor Labs does not build your code, so all dependencies and vendor code must be included within the source. If the build process pulls in additional packages, they must also be present in the scanned directory. Endor Labs analyzes source code using a combination of code signatures and embeddings. The system extracts source code from multiple data sources and applies language-specific segmentation to break the code into functions and segments. This method facilitates efficient similarity searches, helping to detect duplicated code across repositories and supporting comprehensive software composition analysis. By comparing file hashes, segment hashes, and embeddings, Endor Labs queries data to identify matches with code segments. This capability streamlines the detection of copied code and dependency relationships between repositories. It provides insights into code components from multiple sources, including Git repositories, online archives, and other package distributions. Endor Labs scans headers and code files regardless of their file extension. To optimize performance, Endor Labs caches embeddings and signatures, making subsequent scans faster than the first scan. This means only newly added or modified files require computation, notably reducing scan times. ### Enable code segment embeddings Endor Labs disables embeddings by default. You need an Endor Labs AI license to use them. To enable embeddings go to **Settings** near the bottom of the left sidebar, navigate to **Data Privacy** under **System Settings**, check the box for **Code Segment Embeddings and LLM Processing** and click **Save Data Privacy Settings**. Enable embeddings To override the system-wide configuration for a specific scan, set `ENDOR_SCAN_EMBEDDINGS` to `true` to enable embeddings or `false` to disable them. This setting takes precedence over the system configuration. ```bash theme={null} export ENDOR_SCAN_EMBEDDINGS=false ``` ## Scan C/C++ projects with segment-based analysis You can enable segment-based analysis for C/C++ using any of the following methods: To scan a C/C++ project using segment-based analysis, use the `--segment-match-languages` flag. ```bash theme={null} endorctl scan --segment-match-languages=c ``` In your scan profile, select **C/C++** under **Segment Match Languages**. See [Configure scan profile settings](/scan/scan-profiles/configure-scanprofile-ui#configure-general-scan-profile-settings) for more information. Adding a language to **Segment Match Languages** scans it with segment-based analysis and does not affect any other selected languages. You can select any combination of languages across all three fields Set `segment_match_languages` under `spec.automated_scan_parameters` when creating a `ScanProfile` object. See [Configure scan profile through Endor Labs API](/scan/scan-profiles/configure-scanprofile-api). ```yaml theme={null} spec: automated_scan_parameters: segment_match_languages: - c ``` Set `segment_match_languages` under `spec` in your `scanprofile.yaml`. See [Configure scan profile through scanprofile.yaml](/scan/scan-profiles/configure-scanprofile-yaml). ```yaml theme={null} kind: "AutomatedScanParameters" spec: segment_match_languages: - c ``` ## Limitations Scanning binary library files such as `.so` and `.a` files is not supported. # Call graphs Source: https://docs.endorlabs.com/scan/sca/call-graphs/index Mitigate open source vulnerabilities with call graph visualizations, pinpointing and understanding the invocation of vulnerable methods for actionable developer insights. Endor Labs has developed a systematic approach to conduct call graph analysis. Here is a structured overview: * **Scope Expansion**: Traditional methods of static analysis typically analyze a single project at a time. Endor Labs, however, expands its scope to include not only the client projects but also their dependencies, often comprising over 100 packages. * **Enhanced Dependency Analysis**: Endor Labs employs static call graphs to conduct detailed dependency analysis, enabling a comprehensive understanding of how different external components interact within client projects. By leveraging these call graphs, Endor Labs aims to minimize false positives and more accurately identify the specific locations of problems in dependencies. * **Multiple Data Sources**: Endor Labs uses both source code and binary artifacts to enrich the analysis. This approach ensures swift results without a heavy reliance on test coverage. * **Benchmarking for Continuous Improvement**: Endor Labs maintains accuracy and relevance by using dynamic call graphs internally to benchmark and refine static call graphs, thereby actively identifying and addressing gaps. * **Scalability**: Endor Labs addresses the challenge of scalability and generates call graphs not only for each project release but also for all its dependencies. This approach effectively manages large projects with multiple versions, ensuring that the analysis remains both relevant and applicable across the entire spectrum of client dependency sets. For more information, see [Visualizing the impact of call graphs on open source security](https://www.endorlabs.com/learn/securing-code-with-beautiful-call-graph-visualizations). Endor Labs uses static call graphs to perform dependency analysis at a fine-grained level. It is minimally intrusive to the developer workflow and provides results during development. The Endor Labs user interface provides visualizations of call graphs that annotate vulnerability data and simplify it into informative call paths. This empowers developers to identify and address problematic invocations of vulnerable methods efficiently. Endor Labs supports call paths for `Java`, `Python`, `Rust`, `JavaScript`, `Golang`, `.NET (C#)`, `Kotlin`, and `Scala`. ### View call paths View call paths in Endor Labs to see the sequences of functions that your program invokes during execution. 1. Select **Projects** from the left sidebar. 2. Select the project for which you want to view the call path. 3. Select **FINDINGS** and select the finding from the list view. 4. Expand a specific finding to view more details. 5. In the details section, select **CALL PATHS**. A finding may have multiple call paths. Call Paths # .NET Source: https://docs.endorlabs.com/scan/sca/dotnet/index Learn how to implement Endor Labs in repositories with .NET packages. .NET is a free, cross-platform, open-source developer platform for building different types of applications. Endor Labs supports the scanning and monitoring of projects built on the .NET platform. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## System specifications for deep scan Before you proceed to run a deep scan, ensure that your system meets the following specification. | Project Size | Processor | Memory | | ----------------- | ----------------- | ------ | | Small projects | 4-core processor | 16 GB | | Mid-size projects | 8-core processor | 32 GB | | Large projects | 16-core processor | 64 GB | ## Software prerequisites Before you begin, verify the following prerequisites: * Make sure your repository includes one or more files with `.cs` extension. * Endor Labs supports dependency resolution and reachability analysis only for SDK-style .NET projects. * One or more `*.csproj` files must be present in your repository. * Install the .NET command or NuGet command and make it available on the host system. * At least one .NET SDK installed on the system must be compatible with the project's `global.json` file settings. To check your available SDK versions you can run the command `dotnet --info` or `dotnet --list-sdks`. ## Run a scan Use the following options to scan your repositories. Perform a scan after building the projects. ### Option 1 - Quick scan Perform a quick scan to get quick visibility into your software composition. This scan won't perform reachability analysis to help you prioritize vulnerabilities. You must restore your .NET projects before running a quick scan. Also verify that packages exist in the local package caches and build artifacts exist in the standard locations. 1. Run the following commands to resolve dependencies and create the necessary files to scan your .NET project. To generate the build artifact `project.assets.json` and resolve dependencies, run: ```bash theme={null} dotnet restore ``` If you use NuGet instead run: ```bash theme={null} nuget restore ``` To create a `packages.lock.json` file if your project uses a lock file run: ```bash theme={null} dotnet restore --use-lock-file ``` If `project.assets.json` or `packages.lock.json` are not present and if the project is buildable, endorctl will restore the project and create a `project.assets.json` or a `packages.lock.json` file to resolve dependencies. 2. You can run a quick scan with the following commands: ```bash theme={null} endorctl scan --quick-scan ``` You can perform the scan from within the root directory of the Git project repository, and save the local results to a `results.json` file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan --quick-scan -o json | tee /path/to/results.json ``` You can sign in to the Endor Labs user interface and navigate to **Projects** from the left sidebar to review your project results. ### Option 2 - Deep scan Use the deep scan to perform dependency resolution, reachability analysis, and generate call graphs. You can do this after you complete the quick scan successfully. You must restore and build your .NET projects before running a deep scan. Also verify that packages exist in the local package caches and build artifacts exist in the standard locations. 1. Run the following commands to restore and build your project. This may vary depending on your project's configuration. ```bash theme={null} dotnet restore dotnet build ``` 2. You can run a deep scan with the following commands: ```bash theme={null} endorctl scan ``` Use the following flags to save the local results to a `results.json` file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan -o json | tee /path/to/results.json ``` During a deep scan, Endor Labs analyzes all private software dependencies in full by default if they have not been previously scanned. This is a one-time operation and will slow down initial scans, but won't impact subsequent scans. Organizations might not own some parts of the software internally and findings are actionable by another team. These organizations can choose to disable this analysis using the flag `disable-private-package-analysis`. By disabling private package analysis, teams can enhance scan performance but may lose insights into how applications interact with first-party libraries. Use the following command flag to disable private package analysis: ```bash theme={null} endorctl scan --disable-private-package-analysis ``` You can sign into the Endor Labs user interface and select **Projects** from the left sidebar to review your project results. ### Configure private NuGet package repositories Endor Labs supports fetching and scanning dependencies from private NuGet package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See [NuGet package manager integrations](/integrations/package-managers/nuget-private-package-manager) for more information on configuring private registries. ## Understand the scan process A `*.csproj` file is an XML-based C# project file that contains information about the project, such as its source code files, references, build settings, and other configuration details. Endor Labs lists the dependencies and findings individually for every `.csproj` file. The scan discovers all `*.csproj` files and uses these files to resolve the appropriate dependency graph of your project. Endor Labs scans the .NET projects that are using the [Central Package Management feature](https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management#enabling-central-package-management) of NuGet for the packages declared as: * Package references in `Directory.Build.props` or `Directory.Packages.props` files. * Package references in any `*.props` file that the `.csproj` file imports. * Package references in `*.Targets` file. You may not be able to view the **Requested version** of the packages on the Endor Labs user interface * For the packages declared as package version in `*.Targets` file. * If you are importing the packages into the `*.csproj` file using MSBuild keywords in the path variables. Endor Labs enriches your dependency graph to help you understand if your dependencies are secure, sustainable, and trustworthy. This includes Endor Labs risk analysis and scores, if a dependency is direct or transitive, and if the source code of the dependency is publicly auditable. Endor Labs performs software composition analysis for .NET in the following ways: * [Using Project.assets.json](#how-does-dependency-resolution-happen-using-project-assets-json) * [Using package.lock.json](#how-does-dependency-resolution-happen-using-package-lock-json) ### How does dependency resolution happen using Project.assets.json .NET projects use the `project.assets.json` file to store metadata and information about the project's dependencies and assets. Endor Labs fetches resolved package versions, paths to the dependencies' assets, such as assemblies and resources, and other related information from this file. If a project does not include a `project.assets.json` file, the `dotnet restore` or `nuget restore` command generates it. This command uses all configured sources to restore dependencies and project-specific tools that the project file specifies. If the host machine has .NET Core or .NET 5+ installed, the dotnet restore command generates the `project.assets.json` file. The `nuget restore` command generates the `project.assets.json` file for earlier versions of the .NET frameworks. ### How does dependency resolution happen using package.lock.json .NET projects use the `package.lock.json` file to lock dependencies and their specific versions. It is a snapshot of the exact versions of packages installed in a project, including their dependencies and sub-dependencies, requested versions, resolved versions, and contenthash. The lock file provides a more dependable, uniform, and accurate representation of the dependency graph. In Endor Labs' dependency management, the resolution of dependencies is primarily based on `package.lock.json`, which takes precedence over `projects.assets.json` to resolve dependencies. Endor Labs fetches the dependency information from `package.lock.json` and creates a comprehensive dependency graph. Endor Labs lists the associated vulnerabilities on the Endor Labs user interface. If the `package.lock.json` file is not present in the repository, Endor Labs triggers the restore process to generate the `package.lock.json` file and uses it to perform the dependency scans. ### Resolving package names from props files endorctl evaluates MSBuild property values that contain variables, as long as the same file defines those variables for example, `Directory.Build.props`. This enables accurate resolution of package names and versions, even if they are not explicitly declared in the `.csproj` file. For example, in a setup like `test.csproj` ```bash theme={null} net8 ``` `Directory.Build.props` ```bash theme={null} via-build-prop $(CompanyName).$(MSBuildProjectName) ``` When generating package names for .NET projects, the system evaluates the `AssemblyName` property defined in the project’s `.props` file. Instead of using a generic name like `test`, the system applies the evaluated value, for example, `via-build-prop.test`. This approach enables consistent and customizable package naming based on MSBuild properties. ### How Endor Labs performs static analysis on the code Endor Labs performs static analysis on the C# code based on the following factors: * Endor Labs creates call graphs for your package and combines them with the dependency call graphs to form a comprehensive call graph for the entire project. * Endor Labs looks for the project's `.dll` files typically located within the bin directory. * Endor Labs performs an inside-out analysis of the software to determine the reachability of dependencies in your project. * The static analysis time may vary depending on the number of dependencies in the package and the number of packages in the project. ### Known Limitations * When using the GitHub app, either resolve all the private and internal dependencies, or [Configure private NuGet package repositories](#configure-private-nuget-package-repositories) before running a scan. * When working with old-style MSBuild projects, we recommend scanning them through [Continuous Integration (CI)](/setup-deployment/ci-cd) after building the project to ensure that the .NET build system generates the required `obj/project.assets.json` file. For [monitoring scans](/setup-deployment/scm-integrations), support for restoring dependencies in Windows projects is limited. This may lead to **restore or build errors**, potentially causing unexpected scan results. ### Call graph limitations * You must install .NET 7.0.1 (SDK 7.0.101) or later on the host system. * The following .NET programming languages are not supported for dependency resolution or call graph generation: * Projects written in F# * Projects written in Visual Basic * Endor Labs bases .NET call graph support on [Microsoft's Common Intermediate Language](https://learn.microsoft.com/en-us/dynamicsax-2012/appuser-itpro/compile-into-net-framework-cil) (CIL). Ensure that artifacts such as `.exe` or `.dll` files exist in the project's standard workspace through a build and restore or a restored cache. ## Troubleshoot errors Here are a few error scenarios that you can check for and attempt to resolve them. * **Host system check failure errors**: .NET or NuGet is not installed or not present in the PATH environment variable. Install NuGet and try again. * **Unresolved dependency errors**: This error occurs when the `.csproj` file can not be parsed or if it has syntax errors. # Go Source: https://docs.endorlabs.com/scan/sca/golang/index Learn how to implement Endor Labs in repositories with Go packages. Go or Golang is a software development programming language widely used by developers. Endor Labs supports scanning and monitoring of Go projects. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## System specifications for deep scan Before you proceed to run a deep scan, ensure that your system meets the following specification. | Project Size | Processor | Memory | | ----------------- | ----------------- | ------ | | Small projects | 4-core processor | 16 GB | | Mid-size projects | 8-core processor | 32 GB | | Large projects | 16-core processor | 64 GB | ## Software prerequisites * Make sure that you have Go 1.12 or higher versions. * Install Bazel version `5.x.x`, `6.x.x`, `7.x.x`, `8.x.x`, or `9.x.x` if your project uses Bazel. Endor Labs supports Bzlmod with Bazel aspects. See [Bazel](/scan/bazel) for more information. * Make sure your repository includes one or more files with `.go` extension. ## Build Go projects You must build your Go projects before running the scan. Also verify that packages exist in the local package caches and that the *go.mod* file is well formed and available in the standard location. To ensure that your go.mod file is well formed, run the following command: ```bash theme={null} go mod tidy ``` Run the following command to remove unnecessary dependencies and verify that all dependencies resolve without errors. ```bash theme={null} go get ./ ``` ## Scan Bazel projects To scan Go projects that use Bazel, see [Bazel](/scan/bazel) for build instructions, supported rules, and scan commands. Endor Labs supports Bzlmod with Bazel aspects. See [Bazel Aspects](/scan/bazel/bazel-aspects) for more information. ## Run a scan Use the following options to scan your repositories. Perform the endorctl scan after building the projects. ### Option 1 - Quick scan Perform a quick scan to get quick visibility into your software composition. This scan won't perform reachability analysis to help you prioritize vulnerabilities. ```bash theme={null} endorctl scan --quick-scan ``` You can perform the scan from within the root directory of the Git project repository, and save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan --quick-scan -o json | tee /path/to/results.json ``` You can sign into the [Endor Labs user interface](https://app.endorlabs.com), click the **Projects** on the left sidebar, and find your project to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ### Option 2 - Deep scan Use the deep scan to perform dependency resolution, reachability analysis, and generate call graphs. You can do this after you complete the quick scan successfully. ```bash theme={null} endorctl scan ``` Use the following flags to save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan -o json | tee /path/to/results.json ``` You can sign into the [Endor Labs user interface](https://app.endorlabs.com), click the **Projects** on the left sidebar, and find your project to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ## Understand the scan process Endor Labs resolves your Golang-based dependencies by leveraging built-in Go commands to replicate the way a package manager would install your dependencies. To discover package names for Go packages Endor Labs uses the command: ```bash theme={null} GOMOD=off go list -e -mod readonly -json -m ``` To analyze the dependency graph of your package Endor Labs uses the command: ```bash theme={null} GOMOD=off go list -e -deps -json -mod readonly all ``` To assess external dependencies, specifically third-party packages or libraries that your Go project relies on, Endor Labs uses the command: ```bash theme={null} GOMOD=off go list -e -deps -json -mod vendor all ``` These commands allow us to assess packages' unresolved dependencies, analyze the dependency tree, and resolve dependencies for your Go projects. ## Go standard library vulnerability scanning Endor Labs performs SCA for the Go standard library by adding the standard library as a dependency in the bill of materials (BOM). The Go version used for the standard library determines which standard library package Endor Labs matches for vulnerability checks. ### Version resolution order Endor Labs determines the Go version for standard library vulnerability scanning using the following precedence order. 1. **Use the system Go version** By default, the scanner uses the version that `go env GOVERSION` reports in the scan environment. For example, if the host has Go 1.23.2 installed, the scanner uses 1.23.2 for scanning. 2. **Pin to a specific Go version**: Set the `ENDOR_SCAN_GO_VERSION` environment variable to specify the Go version used for standard library vulnerability scanning. For example, setting `ENDOR_SCAN_GO_VERSION` to `1.23.4` ensures that the scanner uses Go 1.23.4 for standard library scanning. ```bash theme={null} export ENDOR_SCAN_GO_VERSION=1.23.4 endorctl scan ``` 3. **Use the version from `go.mod`** Set `ENDOR_SCAN_USE_GOMOD_VERSION=true` to instruct endorctl to use the version specified in the `go` directive of the module's `go.mod` file instead of detecting the system Go version. ```bash theme={null} export ENDOR_SCAN_USE_GOMOD_VERSION=true endorctl scan ``` For example, if the go.mod file contains go 1.22 and the host system has Go 1.23 installed, the scanner uses Go 1.22 for vulnerability checks. **Fallback behavior** If the scanner cannot detect the system Go version, it falls back to the version in the `go` directive in your module’s `go.mod` file. ## Known limitations Endor Labs creates `go.mod` files for you when projects do not have a `go.mod` file. This can lead to inconsistencies with the actual package created over time and across versions of the dependencies. ## Troubleshoot errors Here are a few error scenarios that you can check for and attempt to resolve them. * **Host system check failure errors**: * Go is not installed or not present in the PATH environment variable. Install Go and try again. * The installed version of Go is lower than 1.12. Install Go version 1.12 or higher and try again. * **Resolved dependency errors**: * A dependency version does not exist or cannot be found. The package may no longer exist in the repository. * If the go.mod file is not well-formed then dependency resolution may return errors. Run `go mod tidy` and try again. * **Call graph errors**: These errors often mean the project won't build. Ensure any generated code is in place and verify that `go build ./...` runs successfully. # SCA (Software Composition Analysis) Source: https://docs.endorlabs.com/scan/sca/index Identify vulnerabilities in open source dependencies with reachability analysis. Software composition analysis is the identification of the bill of materials for first-party software packages and the mapping of vulnerabilities to these software component versions. SCA helps teams to maintain compliance and get visibility into the risks of their software inventory. Endor Labs does not scan the files and paths included in `.gitignore` files during SCA scans. If certain dependencies or paths are not appearing in your scan results, verify they are not excluded by your `.gitignore` configuration. Endor Labs supports the following major capabilities to help teams reduce the risk and expense of software dependency management across the lifecycle of software reuse. * [**Endor Scores**](/scan/sca/scores): Endor Labs provides a holistic risk score that includes the security, quality, popularity and activity of a package. Risk scores help in identifying leading indicators of risk in addition to if a software component is outdated, or unmaintained. Risk analysis helps teams to go beyond vulnerabilities and approach the risk of their software holistically. * [**Reachability Analysis**](/scan/sca/reachability-analysis): Reachability analysis is Endor Labs' capability to perform static analysis on your software packages to give context to how each vulnerability may be reached in the context of your code. This includes mapping vulnerabilities back to vulnerable functions so that deep static analysis can target vulnerabilities with higher levels of granularity as well as the identification of unused software dependencies. * [**Upgrade Impact Analysis**](/risk-remediation/upgrade-impact-analysis): Upgrade impact analysis allows security teams to set better expectations with their development teams by identifying breaking changes associated with an update of a direct dependency. The resource requirements, both minimum and recommended, for build runners or workers executing scans using **endorctl** are listed here. Large applications may require additional resources to complete or enhance the scan performance. ## System specifications for local and CI/CD scan Ensure that your local machine or CI/CD runner has the minimum and recommended resources to successfully scan your software. ## Supported languages For scanning monorepos or projects that use **Bazel** as the build tool (Java, Kotlin, Go, JavaScript, Python, Scala, Rust, Swift), see [Bazel](/scan/bazel). ## Complete support matrix The following comprehensive matrix lists the supported languages, build tools, manifest files, and supported requirements. Define supported languages when running endorctl `scan` command as a comma-separated list: # Java Source: https://docs.endorlabs.com/scan/sca/java/index Learn how to implement Endor Labs in repositories with Java packages. Java is a high-level, object-oriented programming language widely used by developers. Endor Labs supports scanning and monitoring of Java projects. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## System specifications for deep scan Before you proceed to run a deep scan, ensure that your system meets the following specification. | Project Size | Processor | Memory | | ----------------- | ----------------- | ------ | | Small projects | 4-core processor | 16 GB | | Mid-size projects | 8-core processor | 32 GB | | Large projects | 16-core processor | 64 GB | ## Software prerequisites Endor Labs requires the following prerequisites in place for successful scans. * Install JDK versions between 11 and 25.0.3 * For JDK 8, see [Scan the projects on JDK version 8](#scan-the-projects-on-jdk-version-8) * Make sure your repository includes one or more files with `.java` extension. * Install Maven Package Manager version 3.6.1 and higher if your project uses Maven. * Install Gradle build system version 6.0.0 and higher, if your project uses Gradle. To support lower versions of Gradle, see [Scan projects on Gradle versions between 4.7 and 6.0.0](#scan-projects-on-gradle-versions-between-4-7-and-6-0-0). * Install Bazel version `5.x.x`, `6.x.x`, `7.x.x`, `8.x.x`, or `9.x.x` if your project uses Bazel. Endor Labs supports Bzlmod with Bazel aspects using `rules_java` >= 5.0.0. See [Bazel](/scan/bazel) for more information. * For projects not using Maven or Gradle, make sure that you set up the project properly to scan without the `pom.xml` file. See [Scan projects without pom.xml](#scan-projects-without-pom-xml) for more information. ## Build Java projects You must build your Java projects before running a scan. Also verify that packages exist in the local package caches and build artifacts exist in the standard locations. ### Use Gradle To analyze your software built with Gradle, Endor Labs requires a successful build. For a quick scan, locate the dependencies in the local package manager cache. The standard `$GRADLE_USER_HOME/caches` or `/User//.gradle/caches` directory must exist and contain downloaded dependencies. For a deep scan, also generate the target artifact on the file system. To build your project with Gradle, use the following procedure: 1. If you would like to run a scan against a custom configuration, specify the Gradle configuration by setting an environment variable. ```bash theme={null} export endorGradleJavaConfiguration="" ``` When there is no configuration, endorctl uses `runtimeClasspath` by default. If neither the user-specified nor the default configuration exists in the project, endorctl falls back to the following configurations, in order: 1. `runtimeClasspath` 2. `runtime` 3. `compileClasspath` 4. `compile` If endorctl does not find the listed configurations in the project, it selects the first available configuration in alphabetical order. 2. Ensure that you can resolve the dependencies for your project without errors by running the following command: For Gradle wrapper: ```bash theme={null} ./gradlew dependencies ``` For Gradle: ```bash theme={null} gradle dependencies ``` 3. Run `./gradlew assemble` or `gradle assemble` to resolve dependencies and create an artifact for deep analysis. #### Override subproject level configuration In a multi-build project, if you set the environment variable `endorGradleJavaConfiguration=[GlobalConfiguration]`, endorctl uses the specified configuration for dependency resolution across all projects and subprojects in the hierarchy below. ```bash theme={null} \--- Project ':samples' +--- Project ':samples:compare' +--- Project ':samples:crawler' +--- Project ':samples:guide' +--- Project ':samples:simple-client' +--- Project ':samples:slack' +--- Project ':samples:static-server' +--- Project ':samples:tlssurvey' \--- Project ':samples:unixdomainsockets' ``` To override the configuration only for the `:samples:crawler` and `:samples:guide` subprojects, follow these steps: 1. Navigate to the root workspace, where you execute `endorctl scan`, and run `./gradlew projects` to list all projects and their names. 2. Run the following command at the root of the workspace: ```bash theme={null} echo ":samples:crawler=testRuntimeClasspath,:samples:guide=macroBenchMarkClasspath" >> .endorproperties ``` This creates a new file named `.endorproperties` in your root directory. This enables different configurations for the specified subprojects in the file. 3. Run `endorctl scan`. At this point, all other projects will adhere to the `GlobalConfiguration`. However, the `:samples:crawler` subproject will use the `testRuntimeClasspath` configuration, and the `:samples:guide` subproject will use the `macroBenchMarkClasspath` configuration. #### Enable monorepo mode for Gradle multi-module projects For large Gradle multi-module projects, you can enable monorepo mode to reduce scan time. When enabled, Endor Labs runs a single Gradle command across all subprojects under each Gradle Wrapper hierarchy. It reuses the output for dependency resolution instead of invoking Gradle separately for each subproject. Your project must meet the following requirements to use monorepo mode: * The project must have a standard Gradle multi-module layout with a single root project and child subprojects. * The project must use the Gradle Wrapper `gradlew`. Plain `gradle` is not supported. To enable monorepo mode, set the `ENDOR_SCAN_GRADLE_MONOREPO_MODE` environment variable before running a scan: ```bash theme={null} export ENDOR_SCAN_GRADLE_MONOREPO_MODE=true endorctl scan ``` For pull request scans of large Maven or Gradle projects, incremental PR scans also skip dependency resolution for packages the pull request does not affect. See [Skip unaffected packages during incremental PR scans](/scan/pr-scans#skip-unaffected-packages-during-incremental-pr-scans). #### Configure private Gradle package repositories Endor Labs supports fetching and scanning dependencies from private Gradle package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See [Gradle package manager integrations](/integrations/package-managers/gradle-private-package-manager) for more information on configuring private registries. ### Use Maven To analyze your software built with Maven, Endor Labs requires a successful build. For a quick scan, locate the dependencies in the local package manager cache. The standard `.m2` cache must exist and contain downloaded dependencies. For a deep scan, also generate the target artifact on the file system. To build your project with Maven, use the following procedure: 1. Ensure that you can resolve the dependencies for your project without error by running the following command. ```bash theme={null} mvn dependency:tree ``` 2. Run `mvn install` and make sure the build is successful. If you want to skip the execution of tests during the build, you can use `-DskipTests` to quickly build and install your projects. ```bash theme={null} mvn install -DskipTests ``` 3. If you have multiple Java modules not referenced in the root pom.xml file, make sure to run `mvn install` separately in all the directories. #### Configure private Maven package repositories Endor Labs supports fetching and scanning dependencies from private Maven package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See [Maven package manager integrations](/integrations/package-managers/maven-private-package-manager) for more information on configuring private registries. ### Scan Bazel projects To scan Java projects that use Bazel, see [Bazel](/scan/bazel) for build instructions, supported rules, and scan commands. Endor Labs supports Bzlmod with Bazel aspects using `rules_java` >= 5.0.0. See [Bazel Aspects](/scan/bazel/bazel-aspects) for more information. ## Run a scan Use the following options to scan your repositories. Perform a scan after building the projects. ### Option 1 - Quick scan Perform a quick scan to get quick visibility into your software composition. This scan won't perform reachability analysis to help you prioritize vulnerabilities. ```bash theme={null} endorctl scan --quick-scan ``` You can perform the scan from within the root directory of the Git project repository, and save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan --quick-scan -o json | tee /path/to/results.json ``` You can sign in to the [Endor Labs user interface](https://app.endorlabs.com), click the **Projects** on the left sidebar, and find your project to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ### Option 2 - Deep scan Use the deep scan to perform dependency resolution, reachability analysis, and generate call graphs. You can do this after you complete the quick scan successfully. ```bash theme={null} endorctl scan ``` Use the following flags to save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan -o json | tee /path/to/results.json ``` During a deep scan, Endor Labs analyzes all private software dependencies in full by default if they have not been previously scanned. This is a one-time operation and will slow down initial scans, but won't impact subsequent scans. Organizations might not own some parts of the software internally and the related findings are not actionable by them. They can choose to disable this analysis using the flag `disable-private-package-analysis`. By disabling private package analysis, teams can enhance scan performance but may lose insights into how applications interact with first-party libraries. Use the following command flag to disable private package analysis: ```bash theme={null} endorctl scan --disable-private-package-analysis ``` You can sign in to the [Endor Labs user interface](https://app.endorlabs.com), click the **Projects** on the left sidebar, and find your project to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ### Scan projects without pom.xml Endor Labs supports projects that do not use Maven or Gradle, and have no `pom.xml` in the following cases. Run the scans with the `--quick-scan` parameter if you prefer to scan the project without reachability. #### Uber jars If you have an uber jar (fat jar) that contains all application classes and dependency jars, set the environment variable `ENDOR_JVM_USE_ARTIFACT_SCAN` to true and run the scan. ```shell theme={null} export ENDOR_JVM_USE_ARTIFACT_SCAN=true endorctl scan --package --path= --project-name= ``` For example: ```shell theme={null} export ENDOR_JVM_USE_ARTIFACT_SCAN=true endorctl scan --package --path=/Users/johndoe/projects/project21.jar --project-name=Project21 ``` #### Application dependencies in classpath If you only have application dependency files (like jar, war, or ear) without an uber jar, set the path to these files in the environment variable `ENDOR_JVM_USE_ARTIFACT_SCAN_CLASSPATH` and run the scan. ```shell theme={null} export ENDOR_JVM_USE_ARTIFACT_SCAN=true export ENDOR_JVM_USE_ARTIFACT_SCAN_CLASSPATH= endorctl scan --package --path= --project-name= ``` For example: ```shell theme={null} export ENDOR_JVM_USE_ARTIFACT_SCAN=true export ENDOR_JVM_USE_ARTIFACT_SCAN_CLASSPATH=/Users/johndoe/caches/modules/files-2.1 endorctl scan --package --path=/Users/johndoe/projects/project21.jar --project-name=Project21 ``` ### Scan the projects on JDK version 8 Endor Labs supports JDK versions between 11-25.0.3, however, you can scan projects on JDK 8 using the following procedure: 1. [Build your Java project](#build-java-projects) on JDK 8. 2. After building, switch your Java home to JDK 11 or higher versions. ```bash theme={null} export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk-11.jdk/Contents/Home ``` 3. [Run a scan](#run-a-scan) ### Scan projects on Gradle versions between 4.7 and 6.0.0 To scan Java projects on Gradle versions between 4.7 and 6.0.0, make sure to 1. Check the version of your project using: ```bash theme={null} ./gradlew --version ``` 2. The project must have a Gradle wrapper. You can generate the Gradle wrapper using: ```bash theme={null} --gradle-version . ``` Endor Labs prioritizes Gradle wrapper over Gradle and it is a recommended best practice to use [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html). 3. Before executing the endorctl scan, ensure the project can be built in your required version. ```bash theme={null} Execute ./gradlew assemble. ``` 4. Use `--bypass-host-check` during endorctl scan to execute scans on projects that have Gradle versions lower than 6.0.0. ## Understand the scan process Endor Labs analyzes your Java code and dependencies to detect known security issues, including open-source vulnerabilities and generates call graphs. ### How Endor Labs resolves dependencies for package versions Endor Labs resolves the dependencies for Java packages based on the following factors: * For packages built using Maven, it leverages the Maven cache in the `.m2` directory of your file system to resolve the package's dependencies and mirrors Maven's build process for the most accurate results. * For Maven, Endor Labs respects the configuration settings in the *settings.xml* file. If your repository includes this file, you need not provide any additional configuration. * For packages built using Gradle, it uses Gradle and Gradle wrapper files to build packages and resolve dependencies. * Endor Labs supports EAR, JAR, RAR, and WAR files. ### How Endor Labs performs static analysis on the code Endor Labs performs static analysis on the Java code based on the following factors: * Endor Labs creates call graphs for your package and combines them with the dependency call graphs to form a comprehensive call graph for the entire project. * Endor Labs performs an inside-out analysis of the software to determine the reachability of dependencies in your project. * The static analysis time may vary depending on the number of dependencies in the package and the number of packages in the project. ### Known limitations * If a package can not be successfully built in the source control repository, static analysis will fail. * Endor Labs analyzes Spring dependencies based on Spring public entry points to reduce the impact of Inversion of Control (IOC) frameworks. Endor Labs identifies dependencies and functions as reachable or unreachable in the context of a Spring version and its entry points. * Annotation processing is limited only to the usage of the code they annotate. * Static analysis of reflection and callbacks are not supported. * Endor Labs requires JDK 11 to generate call graphs for Java projects. Gradle versions lacking JDK 11 support are not compatible. ## Troubleshoot errors Here are a few error scenarios that you can check for and attempt to resolve them. * **Host system check failure errors**: * Java is not installed or not present in the PATH environment variable. Install Java and try again. See [Java documentation](https://www.oracle.com/java/technologies/downloads/) for more information. * The installed version of Java is lower than the required version. Install JDK versions between 11-25.0.3 and try again. * Java is installed but Maven or Gradle is not installed. In such cases, the dependency resolution may not be complete. * **Unresolved dependency errors**: Maven is not installed properly or the system is unable to build root pom.xml. Run `mvn dependency:tree` in the root of the project and try again. In such cases, the dependency resolution may not be complete. * **Resolved dependency errors**: A dependency version does not exist or cannot be found. The package may no longer exist in the repository. * **Gradle variant incompatibility message**: Gradle performs JVM toolchain checks for subprojects or dependencies and may raise errors indicating a Java version mismatch between dependencies declared in Gradle manifest and Java home setup. Example error message: ```shell theme={null} *Incompatible because this component declares a component for use during compile-time, compatible with Java version 21 and the consumer needed a component for use during runtime, compatible with Java version 17* ``` * To resolve this, use Java's backward compatibility and instruct Gradle to use the higher JDK version from the error message. Specify `org.gradle.java.home=` in `.gradle/gradle.properties`. The path must point to the root of the directory containing `bin/java`. For example, if your Java is at `/Users/Downloads/jdk-21/Contents/Home/bin/java`, specify `org.gradle.java.home=/Users/Downloads/jdk-21/Contents/Home`. * If you are scanning a purely Java 8 Gradle project and if you encounter the above error, set `org.gradle.java.home` to point to Java 8 home, before you execute the endorctl scan. * A general guideline for determining which Java version to use, is to match the Java version specified in `.gradle`/`gradle.properties` with the one used for building your Gradle project. * **Call graph errors**: * endorctl cannot build the project because it cannot locate a dependency in the repository. * Sometimes the build fails if a Java version discrepancy exists between the required repository version and the version on the system running the scan. For example, the Java required version is 1.8 but the system has 12 installed. Install the required version and try again. * If you have a private registry and internal dependencies on other projects, you must configure the credentials of the registry. See [Configure Maven private registries](#configure-private-maven-package-repositories). * If you have a large repository or if the scan fails with out-of-memory issues, you may need to increase the JVM heap size before you can successfully scan. Export the `ENDOR_SCAN_JVM_PARAMETERS` environment variable with additional JVM parameters before performing the scan as shown below: ```bash theme={null} export ENDOR_SCAN_JVM_PARAMETERS="-Xmx32G" ``` * If you use a remote repository configured to authenticate with a client-side certificate, you must add the certificate through an endorctl parameter. Export the `ENDOR_SCAN_JVM_PARAMETERS` parameter before performing a scan. See [Maven documentation](https://maven.apache.org/guides/mini/guide-repository-ssl.html) for details. ```bash theme={null} export ENDOR_SCAN_JVM_PARAMETERS="-Xmx16G,-Djavax.net.ssl.keyStorePassword=changeit, -Djavax.net.ssl.keyStoreType=pkcs12, -Djavax.net.ssl.keyStore=/Users/myuser/Documents/nexustls/client-cert1.p12" ``` # JavaScript/TypeScript Source: https://docs.endorlabs.com/scan/sca/javascript/index Learn how to implement Endor Labs in repositories with JavaScript or TypeScript packages. JavaScript is a high-level, interpreted programming language primarily used for creating interactive and dynamic web content widely used by developers. Endor Labs supports the scanning and monitoring of JavaScript projects. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## System specifications for deep scan Before you proceed to run a deep scan, ensure that your system meets the following specification. | Project Size | Processor | Memory | | ----------------- | ----------------- | ------ | | Small projects | 4-core processor | 16 GB | | Mid-size projects | 8-core processor | 32 GB | | Large projects | 16-core processor | 64 GB | ### Software prerequisites * Install the following software before you scan: * Yarn: Any version * npm: 6.14.18 or higher versions * pnpm: 3.0.0 or higher versions * Rush: 5.90.0 or higher versions. To enable Rush support, set the environment variable `ENDOR_RUSH_ENABLED=true`. * Install Bazel version `5.x.x`, `6.x.x`, `7.x.x`, `8.x.x`, or `9.x.x` if your project uses Bazel. Endor Labs supports Bzlmod with Bazel aspects. See [Bazel](/scan/bazel) for more information. * Make sure your repository includes one or more files with `.js` or `.ts` extension. To run deep scanning for JavaScript and TypeScript projects make sure you have the following prerequisites installed: * Install endorctl version 1.7.0 or higher. * Install Node.js version 4.2.6 or higher to support the required TypeScript version. * Install a TypeScript version greater than 4.9 and up to 6.X.X. * Install `tsserver`. TypeScript includes `tsserver`, so installing the right TypeScript version also installs `tsserver`. Install the appropriate TypeScript version based on your Node.js version. * Use the following command based on your Node.js version to install typescript: ```bash theme={null} npm install -g typescript@6 ``` ```bash theme={null} npm install -g typescript@5.0 ``` ```bash theme={null} npm install -g typescript@4.9 ``` * Run the following command to verify the `tsserver` installation ```bash theme={null} which tsserver ``` If you are running the endorctl scan with `--install-build-tools`, you don't need to install `tsserver`. See [Configure build tools](/scan/scan-profiles/build-tools) for more information. ### Build JavaScript projects You can build your JavaScript projects before running a scan. Building first creates a `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` file, which speeds up the scan. Ensure your repository has `package.json` and run the following command making sure it builds the project successfully. ```bash theme={null} npm install ``` ```bash theme={null} yarn install ``` ```bash theme={null} pnpm install ``` If the project is not built, endorctl builds the project during the scan and generates `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` file. Make sure that npm, Yarn, or pnpm is available on your system. If your repository includes a lock file, endorctl uses the existing file for dependency resolution and does not create it again. The `npm install` command may fail in a subdirectory if your project has a `package-lock.json` file at the root of the repository but not in sub-packages. See the following example. ```text theme={null} . ├── package.json ├── package-lock.json └── sub-package/ └── package.json ``` You need to instruct endorctl to use the root-level lock file to avoid scan failures in monorepo setups where dependencies are centrally managed at the root. Set the following environment variable before you run the scan. ```bash theme={null} export ENDOR_JS_USE_ROOT_DIR_LOCK_FILE=true ``` ### Specify a custom lock file location Use `ENDOR_JS_LOCK_FILE_PATH` to specify the exact lock file for endorctl to use during a scan. This is useful when the lock file doesn't live in the package directory or the repository root, for example, in monorepos, nested projects, or custom build setups. The variable applies to npm, Yarn, pnpm, and Rush projects. `ENDOR_JS_LOCK_FILE_PATH` takes precedence over `ENDOR_JS_USE_ROOT_DIR_LOCK_FILE` and over the default package-directory and workspace-root discovery logic. The value can be a path relative to the repository root or an absolute path. The basename must be one of `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, or `pnpm-lock.yaml`. You can set only one lock file path at a time. For monorepos with multiple package managers or lock files, run separate scans and set the variable to the appropriate lock file for each scan. ```bash theme={null} # Relative to the repository root export ENDOR_JS_LOCK_FILE_PATH=locks/yarn.lock # Or an absolute path export ENDOR_JS_LOCK_FILE_PATH=/abs/path/pnpm-lock.yaml ``` If the file is missing or the basename doesn't match the detected package manager, `endorctl` logs a warning and falls back to the default lock file discovery. ### Scan Rush monorepos Rush is a monorepo management tool for JavaScript/TypeScript that works on top of npm, pnpm, or Yarn and manages multiple projects in a single repository using a centralized configuration. Endor Labs detects Rush repositories using the `rush.json` file at the repository root and scans them with the standard JavaScript workflow. Endor Labs infers the package manager and uses the corresponding lock file for dependency resolution. Run the following command at the repository root to build the repository before a scan and to ensure the appropriate lock file exists. ```bash theme={null} rush install ``` To scan Rush monorepos, you must first enable Rush detection. ```bash theme={null} export ENDOR_RUSH_ENABLED=true ``` Run `endorctl scan` to discover Rush dependencies. ```bash theme={null} endorctl scan ``` ### Configure call graph generation timeout When generating call graphs for JavaScript/TypeScript projects, endorctl uses `tsserver` to analyze the code. By default, `tsserver` waits 15 seconds for a response before timing out. For large or complex projects, you may need to increase this timeout. Set the `ENDOR_JS_TSSERVER_TIMEOUT` environment variable to specify the timeout in seconds. ```bash theme={null} export ENDOR_JS_TSSERVER_TIMEOUT=30 ``` Increasing the timeout might be beneficial in the following scenarios: * Large monorepos with many TypeScript files * Projects with complex type hierarchies * Projects with extensive type checking requirements ### Override JavaScript package manager detection endorctl detects the JavaScript package manager automatically. You can override this detection by setting the `ENDOR_JS_PACKAGE_MANAGER` environment variable to `npm`, `yarn`, `pnpm`, or `lerna`. For example, to use `npm` as the package manager run the following command. ```bash theme={null} export ENDOR_JS_PACKAGE_MANAGER=npm ``` This setting forces endorctl to use the specified package manager and overrides all other JavaScript package manager configuration variables. ## Scan Bazel projects Endor Labs supports Bazel scans for JavaScript and TypeScript with Bazel aspects. See [Bazel](/scan/bazel) for build instructions, supported rules, and scan commands. See [Bazel Aspects](/scan/bazel/bazel-aspects) for more information. * **[rules\_js](https://github.com/aspect-build/rules_js)** (>= 2.0.0): scan targets such as `js_binary` and `js_library`. Supports Bzlmod. Pass `--use-bazel-aspects`. * **[rules\_ts](https://github.com/aspect-build/rules_ts)** (>= 1.0.0): scan targets such as `ts_project` and `ts_project_rule`. Supports both the WORKSPACE model and Bzlmod. Pass `--use-bazel-aspects`. ### Scan TypeScript projects with rules\_ts Ensure that the following prerequisites are in place: * A Bazel workspace (WORKSPACE or `MODULE.bazel`) * `rules_ts` >= 1.0.0 in your workspace * endorctl with `--use-bazel-aspects` Run the following command to discover TypeScript targets. ```bash theme={null} bazel query 'kind(ts_project, //...)' ``` Run the following command to scan those targets. ```bash theme={null} endorctl scan --use-bazel --use-bazel-aspects \ --bazel-targets-query='kind(ts_project, //...)' ``` For call graph generation on TypeScript sources, endorctl uses `tsserver`. Large repositories may need a higher timeout. See [Configure call graph generation timeout](#configure-call-graph-generation-timeout). ## Run a scan Perform a scan to get visibility into your software composition and resolve dependencies. ```bash theme={null} endorctl scan ``` ### Understand the scan process Dependency analysis tools analyze the lock file of an npm, yarn, pnpm, or Rush based package and attempt to resolve dependencies. To resolve dependencies from private repositories, Endor Labs reads the `.npmrc` settings from the repository. Endor Labs surpasses mere manifest file analysis by expertly resolving JavaScript dependencies and identifies: * Dependencies listed in the manifest file but not used by the application * Dependencies used by the application but not listed in the manifest file * Dependencies listed in the manifest as transitive but used directly by the application * Dependencies categorized as test in the manifest, but used directly by the application Developers can eliminate false positives, false negatives, and easily identify test dependencies with this analysis. Endor Labs tags dependencies found in source code but not declared in the manifest files as **Phantom**. Endor Labs also supports npm, Yarn, pnpm, and Rush workspaces out-of-the-box. If your JavaScript frameworks and packages use workspaces, Endor Labs will automatically take the dependencies from the workspace to ensure that the package successfully builds. The lock file speeds up the scan when it exists in the repository. endorctl skips the build step and uses the existing files for analysis. ### Configure private npm package repositories Endor Labs supports fetching and scanning dependencies from private npm package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See [npm package manager integrations](/integrations/package-managers/npm-private-package-manager) for more information on configuring private registries. ### Known Limitations * Endor Labs doesn't currently support local package references * If a dependency cannot resolve from the lock file, building that specific package may fail. The package may no longer exist in npm, or the `.npmrc` file may not be properly configured. Other packages in the workspace are scanned as usual. #### Call graph limitations * The call graph might not include functions passed as arguments to call expressions. * The call graph might not include functions that return and then execute. * The call graph might not include functions assigned to a variable based on a runtime value. * The call graph might not include functions assigned to an array element. ### Troubleshoot errors * **Unresolved dependency errors**: The manifest file `package.json` is not buildable. Try running `npm install`, `yarn install`, `pnpm install`, or `rush install` in the root project to debug this error. * **Resolved dependency errors**: A dependency version does not exist or cannot be found. The package may no longer exist in the repository. # Kotlin Source: https://docs.endorlabs.com/scan/sca/kotlin/index Learn how to implement Endor Labs in repositories with Kotlin packages. Kotlin is a statically typed programming language that runs on the Java Virtual Machine (JVM), known for its concise syntax, null safety, and seamless integration with Java. Endor Labs supports scanning and monitoring of Kotlin projects. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## System specifications for deep scan Before you proceed to run a deep scan, ensure that your system meets the following specification. | Project Size | Processor | Memory | | ----------------- | ----------------- | ------ | | Small projects | 4-core processor | 16 GB | | Mid-size projects | 8-core processor | 32 GB | | Large projects | 16-core processor | 64 GB | ## Software Prerequisites * Install JDK versions between 11 and 25.0.3. * For JDK 8, see [Scan projects on JDK version 8](#scan-the-projects-on-jdk-version-8). * Make sure your repository includes one or more files with `.kt` extension. * Install Maven version 3.6.1 and higher if your project uses Maven. * Install Gradle build system version 6.0.0 and higher, if your project uses Gradle. * To support lower versions of Gradle, see [Scan projects on older Gradle versions](/scan/sca/java#scan-projects-on-gradle-versions-between-4-7-and-6-0-0). * Install Bazel version `5.x.x`, `6.x.x`, `7.x.x`, `8.x.x`, or `9.x.x` if your project uses Bazel. Endor Labs supports `rules_kotlin` >= 2.0.0 with Bazel aspects. See [Bazel](/scan/bazel) for more information. * Your repository must include the appropriate build manifest file: * `pom.xml` for Maven projects. * `build.gradle` or `build.gradle.kts` for Gradle projects. ## Build Kotlin projects Before initiating a scan with Endor Labs, ensure that your Kotlin projects build successfully. Also verify that packages exist in local package caches and build artifacts exist in their standard locations. Follow the guidelines to use Gradle and Maven: ### Use Gradle To analyze your software built with Gradle, Endor Labs requires: * Successfully build the software with Gradle. * For quick scans, locate dependencies in the local package manager cache. The standard `$GRADLE_USER_HOME/caches or /User/<>/.gradle/caches` cache must exist. * For deep scans, generate the target artifact on the filesystem. To build your project with Gradle, run the following commands: 1. Specify the Gradle configuration by setting an environment variable. ```bash theme={null} export endorGradleKotlinConfiguration="compileClasspath" ``` To override the default configuration, use the command: ```bash theme={null} export endorGradleKotlinConfiguration="" ``` When there is no configuration, endorctl uses `runtimeClasspath` by default. If neither the user-specified nor the default configuration exists in the project, endorctl falls back to the following configurations, in order: 1. `runtimeClasspath` 2. `runtime` 3. `compileClasspath` 4. `compile` If endorctl does not find the listed configurations in the project, it selects the first available configuration in alphabetical order. **For Android projects**, you can set the configuration using: ```bash theme={null} export endorGradleAndroidConfiguration="" ``` The default configuration for an Android application or library follows the structure used by Android Studio. Applications: endorctl examines all possible combinations of application variants. Libraries: endorctl examines all possible combinations of library variants. endorctl suffixes the first variant in the alphabetically sorted list with `RuntimeClasspath`. For example, if the first variant is `configA`, the default configuration is `configARuntimeClasspath`. If these methods don’t yield a value, endorctl defaults to `releaseRuntimeClasspath`. 2. Confirm an error-free dependency resolution for your project. ```bash theme={null} gradle dependencies ``` or, with a Gradle wrapper. ```bash theme={null} ./gradlew dependencies ``` 3. Generate the artifact for deep analysis. ```bash theme={null} gradle assemble ``` or, with a Gradle wrapper. ```bash theme={null} ./gradlew assemble ``` #### Override sub project level configuration In a multi-build project, if you set the environment variable `endorGradleKotlinConfiguration=[GlobalConfiguration]` and/or `endorGradleAndroidConfiguration=[GlobalConfiguration]`, endorctl uses the specified configuration for dependency resolution across all projects and sub-projects in the hierarchy below. ```bash theme={null} \--- Project ':samples' +--- Project ':samples:compare' +--- Project ':samples:crawler' +--- Project ':samples:guide' +--- Project ':samples:simple-client' +--- Project ':samples:slack' +--- Project ':samples:static-server' +--- Project ':samples:tlssurvey' \--- Project ':samples:unixdomainsockets' ``` To override the configuration only for the `:samples:crawler` and `:samples:guide` sub-projects, follow these steps: 1. Navigate to the root workspace, where you execute `endorctl scan`, and run `./gradlew projects` to list all projects and their names. 2. Run the following command at the root of the workspace: ```bash theme={null} echo ":samples:crawler=testRuntimeClasspath,:samples:guide=macroBenchMarkClasspath" >> .endorproperties ``` This creates a new file named `.endorproperties` in your root directory. This enables different configurations for the specified sub-projects in the file. 3. Run `endorctl scan` as usual. At this point, all other projects will adhere to the `GlobalConfiguration`. However, the `:samples:crawler` sub-project will use the `testRuntimeClasspath` configuration, and the `:samples:guide` sub-project will use the `macroBenchMarkClasspath` configuration. ### Use Maven To analyze your software built with Maven, Endor Labs requires: * Successfully build the software with Maven. * For quick scans, locate dependencies in the local package manager cache. The standard `.m2` cache must exist. * For deep scans, generate the target artifact on the filesystem. To build your project with Maven, run the following commands: 1. Confirm an error-free dependency resolution for your project. ```bash theme={null} mvn dependency:tree ``` 2. Run `mvn install` and ensure the build is successful. If you want to skip the execution of tests during the build, you can use `-DskipTests` to quickly build and install your projects. ```bash theme={null} mvn install -DskipTests ``` 3. If you have multiple Kotlin modules not referenced in the root **pom.xml** file, ensure to run `mvn install` separately in each directory. ### Configure Maven private registries Endor Labs supports fetching and scanning dependencies from private Maven package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See [Maven package manager integrations](../../../integrations/package-managers/maven-private-package-manager/) for more information on configuring private registries. ### Scan Bazel projects To scan Kotlin projects that use Bazel, see [Bazel](/scan/bazel) for build instructions, supported rules, and scan commands. Endor Labs supports software composition analysis and reachability analysis for `kt_jvm_library`, `kt_jvm_binary`, and `kt_jvm_test` targets built with `rules_kotlin` >= 2.0.0. See [Bazel Aspects](/scan/bazel/bazel-aspects) for more information. ## Run a scan To scan your repositories with Endor Labs, you can use the following options after building your Kotlin projects. ### Option 1 - Quick scan To quickly gain insight into your software composition, initiate a quick scan using the following command: ```bash theme={null} endorctl scan --quick-scan ``` This scan offers a quick overview without performing reachability analysis, helping you prioritize vulnerabilities. #### Save local results To scan a Git project repository from the root directory and save the results locally in the results.json file, use the following command: ```bash theme={null} endorctl scan --quick-scan -o json | tee /path/to/results.json ``` This generates comprehensive results and analysis information, accessible from the Endor Labs user interface. #### Access results To access and review detailed results, sign in to the [Endor Labs user interface](https://app.endorlabs.com). Navigate to **Projects** on the left sidebar, and locate your project for a thorough examination of the scan results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ### Option 2 - Deep scan To perform dependency resolution and reachability analysis, use deep scan with Endor Labs. Use this option only after you successfully complete the quick scan. ```bash theme={null} endorctl scan ``` #### Save local scan results To save the local results to a *results.json* file, use the following flag. ```bash theme={null} endorctl scan -o json | tee /path/to/results.json ``` This generates comprehensive results and analysis information, accessible from the Endor Labs user interface. #### Analyze private packages During deep analysis, Endor Labs thoroughly analyzes all private software dependencies that have not been previously scanned. While this initial operation may slow down scans, subsequent scans remain unaffected. If your organization does not own specific software parts and related findings are non-actionable, you can choose to disable this analysis using the `disable-private-package-analysis` flag. Disabling private package analysis enhances scan performance but may result in a loss of insights into how applications interact with first-party libraries. To disable private package analysis, use the following command flag: ```bash theme={null} endorctl scan --disable-private-package-analysis ``` #### Access scan results To access and review detailed results, sign in to the [Endor Labs user interface](https://app.endorlabs.com). Navigate to **Projects** on the left sidebar, and locate your project for a thorough examination of the scan results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ### Scan the projects on JDK version 8 While Endor Labs primarily supports JDK versions between 11-25.0.3, you can still scan projects on JDK 8 by following these steps: 1. Build your Java project on JDK 8. 2. After successful build, switch your Java home to JDK 11 or higher versions. ```bash theme={null} export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk-11.jdk/Contents/Home ``` 3. Run a scan. ## Understand the scan process Endor Labs analyzes your Kotlin code and dependencies to identify known security issues, including open-source vulnerabilities. ### How Endor Labs resolves dependencies for package versions Endor Labs resolves Kotlin package dependencies by considering the following factors: * For packages built with Maven, it leverages the Maven cache in the `.m2` directory of your file system. This mirrors Maven's build process for precise results. * For packages built with Maven, it respects the configuration settings in the *settings.xml* file. If your repository includes this file, no additional configuration is necessary. * For packages built with Gradle, it leverages Gradle and Gradle wrapper files to build and resolve dependencies. * Endor Labs supports AAR, EAR, JAR, RAR, and WAR files. ### How Endor Labs performs static analysis on the code Endor Labs performs static analysis on the code based on the following factors: * Endor Labs creates call graphs for your package and combines them with the dependency call graphs to form a comprehensive call graph for the entire project. * Endor Labs performs an inside-out analysis of the software to determine the reachability of dependencies in your project. * The static analysis time may vary depending on the number of dependencies in the package and the number of packages in the project. ### Known limitations * If a package can not be successfully built in the source control repository, static analysis will fail. * Endor Labs analyzes Spring dependencies based on Spring public entry points to reduce the impact of Inversion of Control (IOC) frameworks. Endor Labs identifies dependencies and functions as reachable or unreachable in the context of a Spring version and its entry points. * Annotation processing is limited only to the usage of the code they annotate. * Static analysis of reflection and callbacks are not supported. * If Endor Labs fails to resolve dependencies using default Kotlin configurations, specify the Kotlin configuration explicitly. * Static analysis for Kotlin projects using Gradle is supported for Kotlin Gradle plugin versions 1.5.30 and higher. ## Troubleshoot errors Here are a few error scenarios that you can check for and attempt to resolve them. * **Host system check failure errors**: * Java is not installed or not present in the PATH environment variable. Install Java and try again. See [Java documentation](https://www.oracle.com/java/technologies/downloads/) for more information. * For android applications, \$ANDROID\_HOME must be specified as an environment variable. * The installed version of Java is lower than the required version. Install JDK versions between 11-25.0.3 and try again. * Java is installed but Maven or Gradle is not installed. In such cases, the dependency resolution may not be complete. * **Unresolved dependency errors**: Maven is not installed properly or the system is unable to build root pom.xml. Run `mvn dependency:tree` in the root of the project and try again. In such cases, the dependency resolution may not be complete. * **Resolved dependency errors**: A dependency version does not exist or cannot be found. The package may no longer exist in the repository. * **Call graph errors**: * If the project is not compiled, call graphs are not generated. Run `gradlew compileKotlin` or `gradlew compileReleaseKotlin` for android based projects before running the scan. * Sometimes, the project is not compiled, if a Kotlin version discrepancy exists between the required repository version and the version on the system running the scan. For example, the Kotlin required version is 1.4 but the system has lower version installed. Install the required version and try again. * If you have a private registry and internal dependencies on other projects, you must configure the credentials of the registry. See [Configure Maven private registries](#configure-maven-private-registries). * If you use a remote repository configured to authenticate with a client-side certificate, you must add the certificate through an endorctl parameter. Export the `ENDOR_SCAN_JVM_PARAMETERS` parameter before performing a scan. See [Maven documentation](https://maven.apache.org/guides/mini/guide-repository-ssl.html) for details. ```bash theme={null} export ENDOR_SCAN_JVM_PARAMETERS="-Xmx16G,-Djavax.net.ssl.keyStorePassword=changeit, -Djavax.net.ssl.keyStoreType=pkcs12, -Djavax.net.ssl.keyStore=/Users/myuser/Documents/nexustls/client-cert1.p12" ``` # PHP Source: https://docs.endorlabs.com/scan/sca/php/index Learn how to implement Endor Labs in repositories with PHP packages using composer. PHP is a popular server-side scripting language primarily used for web development. Endor Labs supports the scanning and monitoring of PHP projects. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## Software prerequisites * Meet one of the following prerequisites: * The PHP project must contain a `composer.json` file. If the project includes the `composer.lock` file it is beneficial, but this is not a mandatory requirement. * If the **composer.lock** file is not present in the repository, it is necessary to have PHP and [Composer](https://getcomposer.org/doc/00-intro.md) installed before running a scan on your local system. * Make sure your repository includes one or more files with `.php` extension. * Endor Labs supports the following PHP and Composer versions: * PHP 5.3.2 and higher versions * Composer 2.2.0 and higher versions Endor Labs does not support Composer 2.9.1. ## Build PHP projects You can build your PHP projects before running a scan. Building first creates the `composer.lock` file. Ensure your repository has `composer.json` and run the following command making sure it builds the project successfully. ```bash theme={null} composer install ``` If the project is not built, endorctl will build the project during the scan and generate `composer.lock`. If the repository includes a `composer.lock`, endorctl uses this file for dependency resolution and does not create it again. ### Configure private Composer package repositories Endor Labs supports fetching and scanning dependencies from private package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See [package manager integrations](/integrations/package-managers/packagist-private-package-manager) for more information on configuring private registries. ## Run a scan Perform a scan to get visibility into your software composition and resolve dependencies. ```bash theme={null} endorctl scan ``` You can perform the scan from within the root directory of the Git project repository, and save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan -o json | tee /path/to/results.json ``` You can sign into the [Endor Labs user interface](https://app.endorlabs.com), click the **Projects** on the left sidebar, and find your project to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ## Understand the scan process Endor Labs discovers all **composer.json** files in your PHP project and uses these files to resolve the dependencies of your packages. Composer is a PHP dependency management tool that enables you to specify the libraries your project relies on and manages the process of installing or updating them. Endor Labs lists the dependencies and findings individually for every **composer.json** file. Endor Labs resolves dependencies using both **composer.json** and **composer.lock** files. Composer generates the **composer.lock** file, which includes resolved versions, package information, transitive dependencies, and other details. The `composer.lock` file ensures deterministic dependency installation by recording exact versions of installed dependencies and their transitive dependencies. If the `composer.lock` file is not present in the repository, Endor Labs generates it and uses it to analyze the operational and security risks of your package's dependencies. Endor Labs fetches the dependency information and creates a comprehensive dependency graph. ### Known Limitations Call graphs are not supported for PHP projects. ## Troubleshoot errors * **Unresolved dependency errors**: The composer.json is not buildable. Try running `composer install` in the root project to debug this error. * **Resolved dependency errors**: A dependency version does not exist or cannot be found. The package may no longer exist in the repository. # Python Source: https://docs.endorlabs.com/scan/sca/python/index Learn how to implement Endor Labs in repositories with Python packages. Python is a high-level, interpreted programming language widely used by developers. Endor Labs supports the scanning and monitoring of Python projects managed by pip, Poetry, PDM, UV, Pipenv, or Bazel. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## System specifications for deep scan Before you proceed to run a deep scan, ensure that your system meets the following specification. | Project Size | Processor | Memory | | ----------------- | ----------------- | ------ | | Small projects | 4-core processor | 16 GB | | Mid-size projects | 8-core processor | 32 GB | | Large projects | 16-core processor | 64 GB | ## Software prerequisites Complete the following prerequisites: * Install Python 3.6 or higher versions. Refer to the [Python documentation](https://www.python.org/downloads/) for instructions on how to install Python. * For UV managed projects, install Python 3.8 or higher. * Use the package manager [pip](https://pip.pypa.io/en/stable/installation/), [Poetry](https://python-poetry.org/docs/), [PDM](https://pdm-project.org/en/latest/), [UV](https://docs.astral.sh/uv/), or [Pipenv](https://pipenv.pypa.io/en/latest/installation.html#installing-pipenv) in your projects to build your software packages. * If you are using pip with Python 3.12 or higher versions, install [setuptools](https://pypi.org/project/setuptools/). * Set up any build, code generation, or other dependencies that your project's packages require. * Organize the project as one or more packages using `setup.py`, `setup.cfg`, `pyproject.toml`, or `requirements.txt` package manifest files. * Install Bazel version `5.x.x`, `6.x.x`, `7.x.x`, `8.x.x`, or `9.x.x` if your project uses Bazel. Endor Labs supports `rules_python` 0.9.0 up to (but not including) 0.30.0 with the WORKSPACE model only. Bzlmod requires `rules_python` 0.30.0 or higher and Bazel aspects. See [Bazel](/scan/bazel) for more information. * Your repository must include a `WORKSPACE` file for WORKSPACE-based projects, or `MODULE.bazel` for Bzlmod projects when you use Bazel with Python. * Make sure your repository includes one or more files with `.py` extension or pass either one of `requirements.txt`, `setup.py`, `setup.cfg` or `pyproject.toml` using the `--include-path` flag. See [Scoping scans](/best-practices/scoping-scans). ## Build Python projects Create a virtual environment and build your Python projects before running the endorctl scan for the most accurate results. Endor Labs attempts to automatically create and configure a virtual environment when you do not provide one, but this may not work for complex projects. Verify that packages exist in the local package caches and build artifacts exist in the standard locations. 1. Configure any private repositories * If you use dependencies from a PyPI compatible repository *other than* `pypi.org`, configure it in the **Integrations** section of the Endor Labs web application. See [Configure private PyPI package repositories](#configure-private-pypi-package-repositories) for more details. 2. Clone the repository and optionally create a virtual environment inside it 1. Clone the repository using `git clone` or an equivalent workflow. 2. Enter the working copy root directory that's created. 3. Create a virtual environment based on your package manager: For **pip or setuptools** * Use `python3 -m venv venv`. Set up the virtual environment in the root folder that you want to scan and name it `venv` or `.venv`. * Install your project's dependencies using `venv/bin/python -m pip install -r requirements.txt` or `venv/bin/python -m pip install`. * If you create the virtual environment outside the project, use one of the methods in [Virtual environment support](#virtual-environment-support) to specify the path of the Python virtual environment to Endor Labs. For **Poetry projects** * Install your project's dependencies using `poetry install`. For **PDM projects** * Install your project's dependencies using `pdm install`. For **Pipenv projects** * Run `pipenv install` in the project directory. This creates a `Pipfile.lock` (if it doesn't exist) and sets up a virtual environment while installing the required packages. ### Virtual environment support Create a virtual environment to ensure consistent and accurate scan results and to verify that all dependencies install correctly before scanning. Automatic setup may encounter issues such as: * Complex dependency chains or conflicting package requirements * Private packages requiring authentication * System-level dependencies not available in the scan environment * Non-standard project structures or custom build scripts Endor Labs attempts to automatically detect, create, or configure virtual environments for your projects. The behavior varies by package manager. endorctl automatically detects and uses existing virtual environments managed by these tools. endorctl automatically creates a temporary virtual environment and deletes it after the scan completes. Install UV on your system for this automatic management to work. endorctl attempts to detect virtual environments in standard locations, such as `venv` or `.venv` directories in your project root. You can also use one of the following methods to specify the virtual environment: * Set up the virtual environment in the root folder that you want to scan and name it **venv** or **.venv**, it is automatically picked up by the Endor Labs application. ```bash theme={null} export PYTHONPATH=/usr/tmp/venv:/usr/tmp/another-venv ``` * Set the environment variable `ENDOR_SCAN_PYTHON_VIRTUAL_ENV` to the path of the virtual environment of your Python project. ```bash theme={null} export ENDOR_SCAN_PYTHON_VIRTUAL_ENV=/usr/tmp/venv ``` * Set the environment variable `ENDOR_SCAN_PYTHON_GLOBAL_SITE_PACKAGES` to true to indicate that a virtual environment is not present and Endor Labs can use the system-wide Python installation packages and modules. ```bash theme={null} export ENDOR_SCAN_PYTHON_GLOBAL_SITE_PACKAGES=true ``` Setting both `ENDOR_SCAN_PYTHON_VIRTUAL_ENV` and `ENDOR_SCAN_PYTHON_GLOBAL_SITE_PACKAGES` environment variables at the same time is currently not supported, and the scan may not be successful. If you do not set up the virtual environment, Endor Labs attempts to set it up with all the code dependencies. Install all dependencies in a virtual environment for the most accurate results. If you use custom scripts without manifest files to assemble your dependencies, set up the virtual environment and install the dependencies first. ### Configure private PyPI package repositories Endor Labs supports fetching and scanning dependencies from private PyPI package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See [PyPI package manager integrations](/integrations/package-managers/pypi-private-package-manager) for more information on configuring private registries. ## Scan Bazel projects To scan Python projects that use Bazel, see [Bazel](/scan/bazel) for build instructions, supported rules, and scan commands. Endor Labs supports `rules_python` 0.9.0 up to (but not including) 0.30.0 with the WORKSPACE model only. Bzlmod requires `rules_python` 0.30.0 or higher with Bazel aspects. Software composition analysis includes reachability analysis. See [Bazel Aspects](/scan/bazel/bazel-aspects) for more information. ## Run a scan Use the following options to scan your repositories. Perform the endorctl scan after building the projects. ### Option 1 - Quick scan Perform a quick scan to get quick visibility into your software composition and perform dependency resolution. It discovers dependencies that the package has explicitly declared. If the package's build file is incomplete then the dependency list will also be incomplete. This scan won't perform reachability analysis to help you prioritize vulnerabilities. ```bash theme={null} endorctl scan --quick-scan ``` You can perform the scan from within the root directory of the Git project repository, and save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan --quick-scan -o json | tee /path/to/results.json ``` Select **Projects** from the left sidebar, and find your project to review its results. ### Option 2 - Deep scan Use the deep scan to perform dependency resolution, reachability analysis, and generate call graphs. You can do this after you complete the quick scan successfully. The deep scan performs the following operations for the Python projects. * Discovers explicitly declared dependencies, * Discovers project dependent OSS packages present in the `venv/global` and `scope/python`. * Performs reachability analysis and generates call graphs. * Detects dependencies used in source code but not declared in the package's manifest files called `phantom dependencies`. ```bash theme={null} endorctl scan ``` Use the following flags to save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan -o json | tee /path/to/results.json ``` During a deep scan, Endor Labs analyzes all private software dependencies in full by default if they have not been previously scanned. This is a one-time operation and will slow down initial scans, but won't impact subsequent scans. Organizations might not own some parts of the software internally and the related findings are not actionable by them. They can choose to disable this analysis using the flag `disable-private-package-analysis`. By disabling private package analysis, teams can enhance scan performance but may lose insights into how applications interact with first-party libraries. Select **Projects** from the left sidebar, and find your project to review its results. ## Understand the scan process Endor Labs uses the following two methods to analyze your Python code. * [Dependency resolution using manifest files](#dependency-resolution-using-manifest-files) * [Dependency resolution using static analysis](#dependency-resolution-using-static-analysis) Endor Labs uses the results from both these methods to perform superior dependency resolution, identify security issues, detect open-source vulnerabilities, and generate call graphs. ### Dependency resolution using manifest files In this method, Endor Labs analyzes the manifest files present in a project to detect and resolve dependencies. Endor Labs analyzes the manifest files in the following priority. For Poetry, PDM, and UV, when both `lock` and `toml` files are present, Endor Labs analyzes both files to detect and resolve dependencies. For pip, Endor Labs analyzes the first available file in the priority list to detect and resolve dependencies, and ignores others. When a scan starts, Endor Labs identifies the package manager by inspecting files such as `pyproject.toml`, `poetry.lock`, `pdm.lock`, `setup.py`, and `requirements.txt`. If Endor Labs discovers `poetry.lock` or `pyproject.toml`, it uses Poetry to build the project. If it discovers `pdm.lock` or `pyproject.toml`, it uses PDM. Otherwise, it uses pip3. #### Example This is an example that demonstrates scanning a Python repository from GitHub on your local system using the **endorctl** scan. This example assumes you run the scan on a Linux or Mac operating system and have the following Endor Labs API key and secret stored in environment variables. See [endorctl flags and variables](/developers-api/cli/environment-variables). * `ENDOR_API_CREDENTIALS_KEY` set to the API key * `ENDOR_API_CREDENTIALS_SECRET` set to the API secret * `ENDOR_NAMESPACE` set to your namespace (you can find this when logged into Endor Labs by looking at your URL: `https://app.endorlabs.com/t/NAMESPACE/...`; it is typically a form of your organization's name) ##### pip ```python theme={null} git clone https://github.com/HybirdCorp/creme_crm.git cd creme_crm python3 -m venv venv source venv/bin/activate venv/bin/python3 -m pip install endorctl scan ``` ##### Poetry ```python theme={null} git clone https://github.com/HybirdCorp/creme_crm.git cd creme_crm poetry lock endorctl scan ``` ##### PDM ```python theme={null} git clone https://github.com/HybirdCorp/creme_crm.git cd creme_crm pdm install endorctl scan ``` ##### UV ```python theme={null} git clone https://github.com/example/repo.git cd repo endorctl scan ``` ##### Pipenv ```python theme={null} git clone https://github.com/example/repo.git cd repo pipenv install endorctl scan ``` The scan for this repository should complete in a few minutes depending on the size of the project. Select **Projects** from the left sidebar, and choose the **helloflas/flask-examples** project to see your scan results. #### Handling custom and multiple requirement files in pip Repositories often use non-standard names for pip requirement files (for example `default.txt`) or split dependencies across multiple `.txt` files. You can let Endor Labs discover those files automatically so you do not have to maintain a fixed list. ##### Auto detection of requirement files Endor Labs can automatically detect alternate pip requirement files in your workspace. It identifies `.txt` files that follow pip requirements format using version specifiers and environment markers and treats them as manifests. To enable auto detection, set `ENDOR_SCAN_ENABLE_PYTHON_REQUIREMENTS_AUTO_DETECT=true` and then run the endorctl scan. ```bash theme={null} export ENDOR_SCAN_ENABLE_PYTHON_REQUIREMENTS_AUTO_DETECT=true endorctl scan ``` ##### Specify requirement files To specify custom file names as requirement files, export the file name using the `ENDOR_SCAN_PYTHON_REQUIREMENTS` environment variable and then run the endorctl scan. ```bash theme={null} export ENDOR_SCAN_PYTHON_REQUIREMENTS=default.txt ``` To resolve dependencies from multiple requirement files, export them as a comma-separated list using the `ENDOR_SCAN_PYTHON_REQUIREMENTS` environment variable and then run the endorctl scan. ```bash theme={null} export ENDOR_SCAN_PYTHON_REQUIREMENTS=default.txt,requirements.txt ``` When you set the `ENDOR_SCAN_PYTHON_REQUIREMENTS` environment variable, Endor Labs considers only the file names specified in the variable for dependency analysis. For example, if you export `default.txt` and also have `requirements.txt` in your repository, `requirements.txt` is not included in the analysis. ### Dependency resolution using static analysis Not all Python projects include manifest files. A project can consist of a series of install statements that custom scripts assemble. Even when manifest files are present, the dependency information and version declared in the manifest file may differ drastically from what the project actually uses. To solve this problem, Endor Labs performs a static analysis on the code, giving you complete visibility of what your code actually uses. * Endor Labs enumerates all Python packages and recognizes the import statements within the project. An import statement brings external modules or libraries into your Python script. * Endor Labs performs a static analysis of the code to match import statements with pre-installed packages and recursively traverses all files to create a dependency tree with the actual versions installed in the virtual environment. * Endor Labs detects dependencies at the system level, identifies which ones resolve, and retrieves the precise name and version information from the library currently in use. * Endor Labs gives you accurate visibility into your project components and helps you understand how they depend on one another. Through this approach, Endor Labs conducts comprehensive dependency management, assesses reachability, and generates integrated call graphs. Endor Labs performs dependency resolution using static analysis on deep scans only. ### Known Limitations * Endor Labs does not support Python versions older than 3.7, but they may work as expected. * If you do not provide a virtual environment, Endor Labs does not assume Python version constraints based on the CI runtime environment. Dependencies appear for all possible Python versions at runtime. If you provide a virtual environment, Endor Labs respects what you installed in it. * Symbolic links in manifest files may cause Endor Labs to duplicate the same package in the project. * If a dependency is not available in the PyPI repository or in a configured private package repository, Endor Labs cannot build the software. Build the package in your local environment before scanning. * Endor Labs treats a project as UV-managed if its `pyproject.toml` file contains the `tool.uv` key. Any member of a UV workspace is also UV-managed, even if its individual manifest file does not include the `tool.uv` key. * When scanning UV workspaces, Endor Labs uses the workspace-level lock file for dependency resolution. Endor Labs does not scan individual workspace members as independent projects, ensuring consistency with UV's workspace architecture. * Endor Labs does not currently detect inline script dependencies defined within Python script files during scanning. #### Call Graph Limitations * The call graph might not include function calls that use dispatch tables. * The call graph might not include function calls that use unresolved variables. * The call graph might not include dynamically modified or extended function calls that declare methods or attributes at runtime. * The call graph might not include functions called indirectly through a function pointer rather than by their direct name. * Install type stubs that provide hints or type annotations for functions, methods, and variables in your Python modules or libraries manually before scanning. * If your project has a `pyproject.toml` file that includes `tools.pyright` section, it overrides Endor Labs settings for Pyright and may result in incorrect call graph results. You will need to remove the `tools.pyright` section from the `pyproject.toml` file. ## Troubleshoot errors Here are a few error scenarios that you can check for and attempt to resolve them. You can identify the errors that may occur during virtual environment installation by looking for the following message in the error logs: *failed to create virtual environment* or *failed to install dependencies*. If your code depends on packages such as **psycopg2**, environment dependencies such as **PostgreSQL** are also required. The endorctl scan may fail if the environment where it is running does not have **PostgreSQL** installed. The default Python version in the scan environment is incompatible with one or more dependencies that the code needs. One or more dependencies are not compatible with the operating system architecture of the local system running the endorctl scan. For example, projects that depend on **PyObjC** run on Mac-based systems but not Linux systems. A few Python libraries are incompatible with x32 architectures and only run on x64 architectures. A dependency version does not exist or cannot be found. The package may no longer exist in the repository. These errors occur if pip or Poetry cannot build the project because a required dependency is missing. # Reachability analysis Source: https://docs.endorlabs.com/scan/sca/reachability-analysis/index Learn how Endor Labs helps you identify which vulnerabilities are exploitable, potentially exploitable, and false positives. Modern software relies on complex code, external libraries, and open-source components (OSS). Managing risks requires understanding where issues come from, such as internal code, OSS, or other external dependencies. Projects contain two types of dependencies, direct and transitive. Developers explicitly add direct dependencies, such as when they include a specific library in a project. Transitive dependencies enter the project indirectly through other libraries. While direct dependencies are easier to track and manage, transitive dependencies can introduce complexity, as they may not be immediately visible in the project's configuration files. Categorizing code as reachable, potentially reachable, or unreachable is another important step. Reachable code is actively invoked during normal execution. Unreachable code, on the other hand, is not used and can accumulate over time, leading to unnecessary complexity and potential issues. Identifying and managing these categories ensures that the codebase remains efficient and maintainable. ## Types of Reachability Analysis Endor Labs offers multiple types of reachability analysis to help you accurately assess vulnerability exposure in your applications. Each type provides different levels of granularity and accuracy depending on your specific use case and available analysis context. * **[Function-level reachability](#function-level-reachability)** and **[Dependency-level reachability](#dependency-level-reachability)**: These analyses run during a full scan, when the project builds successfully and Endor Labs generates complete call graphs. They use actual code paths and dependency metadata to provide the most precise vulnerability assessment. * **[Pre-computed reachability](/scan/sca/reachability-analysis/pre-computed-reachability)**: A pragmatic, manifest-based analysis technique that enables you to assess whether vulnerabilities in transitive dependencies could be reachable from your direct dependencies—all without requiring code compilation, builds, or full call graph generation. With approximately **95%** of vulnerabilities existing in transitive dependencies according to [Endor Labs' State of Dependency Management report](https://www.endorlabs.com/state-of-dependency-management), pre-computed reachability helps you deprioritize security issues that can't be called by your application by filtering out vulnerabilities that affect functions in transitive dependencies that are not used by your direct dependencies. This approach works by analyzing how your direct dependencies interact with their transitive dependencies, providing valuable reachability insights as a fallback for full scans when builds fail, or as an optional enhancement for quick scans when you want reachability analysis without build requirements. [Learn more about pre-computed reachability](/scan/sca/reachability-analysis/pre-computed-reachability). ### Function-level reachability To help developers and security teams make informed decisions for SCA results, Endor Labs uses a static analysis technique called program analysis to perform **function-level reachability analysis** on direct and transitive dependencies. This is the most accurate way to determine exploitability in the context of your application, which is critical for determining which risks you should remediate. #### Function-level reachability labels The different function reachability labels include: * **Reachable Function**: Endor Labs has determined that there is a path from the developer-written code to a vulnerable function, indicating that the finding is exploitable in your environment. This is demonstrated by a call graph that illustrates each step between the source code and the vulnerable library. * **Unreachable Function**: Endor Labs determines that no risk of exploitation exists, as no path exists from the source code to the vulnerable function. A call graph supports this conclusion by demonstrating the absence of such a path. * **Potentially Reachable Function**: Endor Labs is unable to determine whether a finding is reachable or unreachable, typically because call graph analysis is unsupported for a given language or package manager. This means that the function in question may be executable in the context of the dependent project, but the analysis cannot definitively determine if it is reachable or not. ### Dependency-level reachability Endor Labs supports **dependency-level reachability** by default for all supported languages. This type of reachability analysis is more coarse-grained than function-level reachability. It indicates that the application uses the imported package somewhere but does not determine whether the source code calls the vulnerable package. Dependency-level reachability serves as a good indicator for prioritization. If you're not actually using the dependency at all, consider removing that dependency. Determining whether your code calls or uses a dependency provides another layer of prioritization you can add to your remediation process. #### Dependency reachability labels The different dependency reachability labels include: * **Reachable Dependency:** Endor Labs established that an imported package is being used somewhere in the application. * **Unreachable Dependency:** Endor Labs determined that the imported dependency is not being used. The customer can use this information to remove the dependency, which is helpful for technical debt reduction initiatives. * **Potentially Reachable Dependency:** Endor Labs cannot definitively determine whether the application uses a dependency, generally because Endor Labs does not support the given language or package manager. ### Comparison of reachability analysis types The following table compares the three types of reachability analysis available in Endor Labs: ## Phantom dependencies Phantom dependencies are packages that your codebase uses but does not explicitly declare in your project's manifest files, for example, `package.json`, or `requirements.txt`. These undeclared dependencies can pose significant security and operational risks, as they may contain vulnerabilities that standard dependency analysis does not track or assess. Identifying and managing phantom dependencies is crucial for accurate reachability analysis and comprehensive risk assessment. ### Detection of phantom dependencies Endor Labs' reachability analysis conducts thorough scans of your codebase to identify functions and methods that both declared and undeclared dependencies invoke. By analyzing the actual usage of packages in your source code, the system identifies phantom dependencies—those that your code uses but does not explicitly declare. This detection ensures that all utilized code paths are assessed for potential vulnerabilities, providing a more accurate and comprehensive security evaluation. # Pre-computed Reachability analysis Source: https://docs.endorlabs.com/scan/sca/reachability-analysis/pre-computed-reachability/index Pragmatically assess vulnerability reachability in transitive dependencies without builds. Filter out irrelevant vulnerabilities and focus your team's time. ## Introduction Modern applications rely on open-source dependencies, with most vulnerabilities (approximately **95%** according to [Endor Labs' State of Dependency Management report](https://www.endorlabs.com/state-of-dependency-management)) existing in transitive (indirect) dependencies rather than direct ones. This means most security risks come from packages you didn't explicitly add to your project, making it challenging to assess which vulnerabilities actually pose a threat to your application. **Pre-computed reachability** is a pragmatic analysis technique that enables you to assess whether vulnerabilities in transitive dependencies could be reachable from your direct dependencies, all without requiring code compilation or builds. It serves two primary purposes: as a fallback mechanism for full scans when builds fail, and as an optional enhancement for quick scans when you want reachability analysis without build requirements. This analysis technique filters out vulnerabilities that affect functions never called within your dependency chain, helping you focus your team's time and attention on the security issues that truly matter. The benefits of pre-computed reachability include: * **Pragmatic and easy**: Results are pre-computed and cached, making it a practical approach to reachability analysis. It works solely from your manifest files (for example, `package.json`, `go.mod`, `pom.xml`, `build.gradle`, and others), requiring no access to your application's built artifacts. * **Excellent noise reduction**: By analyzing how your direct dependencies interact with transitive dependencies, pre-computed reachability can filter out a significant portion of irrelevant vulnerabilities, enabling you to focus your team's time on the security issues that truly matter. * **Build-independent**: Works without requiring builds or compilation, making it a pragmatic option when you want reachability analysis without build setup. * **Reliable fallback for full scans**: When builds fail or call graph generation isn't possible, pre-computed reachability ensures you still get actionable security insights rather than missing out on reachability analysis entirely. ## Getting Started **Pre-computed reachability is automatically used as the default fallback for full scans** when builds fail or call graph generation isn't possible, ensuring you always get reachability insights. **For quick scans, pre-computed reachability is optional** and can be enabled using the `ENDOR_SCAN_ENABLE_PRECOMPUTED_CALLGRAPHS` flag. To enable pre-computed reachability analysis, use the `ENDOR_SCAN_ENABLE_PRECOMPUTED_CALLGRAPHS` flag: ```bash theme={null} export ENDOR_SCAN_ENABLE_PRECOMPUTED_CALLGRAPHS=true ``` The system uses pre-computed reachability analysis in the following scenarios: * **Full Scan**: When you run `endorctl scan`, the system attempts full call graph generation first for maximum precision. If the build fails or call graph generation isn't possible, it automatically falls back to pre-computed reachability by default, ensuring you still get valuable reachability insights. * **Quick Scan**: When you run `endorctl scan --quick-scan`, you can optionally enable pre-computed reachability analysis by setting the `ENDOR_SCAN_ENABLE_PRECOMPUTED_CALLGRAPHS` flag. This provides reachability insights without requiring builds. Endor Labs supports pre-computed reachability for the following languages: `java`, `javascript`, `typescript`, `kotlin`, `python`, `scala`, and `C#`. ### Scan modes and pre-computed reachability Endor Labs supports multiple scan modes that can utilize pre-computed reachability analysis. For full scans, pre-computed reachability is automatically used as the default fallback when needed. For quick scans, it is optional and requires the flag to be enabled. The following table summarizes how pre-computed reachability is used across different scan modes: ## How Pre-computed Reachability Works Pre-computed reachability analysis evaluates transitive dependencies using a simple but effective approach: it assumes that everything in your direct dependencies is reachable, then uses that assumption to assess whether vulnerabilities in transitive dependencies could be called. ### From Manifest to Dependency Graph The analysis begins with your manifest files (`package.json`, `go.mod`, `Gemfile`, `pom.xml`, `build.gradle`, and others). Endor Labs resolves your dependencies to build a complete list of direct and transitive dependencies—along with the dependency graph that connects them. **Dependency resolution is required to identify all transitive dependencies, but no build or compilation is necessary.** ### Computing Vulnerability Reachability For every detected CVE in a transitive dependency, the analysis works as follows: 1. **Assume direct dependencies are fully reachable**: Pre-computed reachability assumes that all functions and code in your direct dependencies are reachable. This includes both open-source dependencies and private, non-open source first-party libraries. This conservative assumption ensures comprehensive coverage without needing to analyze your application's source code. 2. **Assess transitive dependency reachability**: Using pre-computed call graph information from open-source dependencies, the system analyzes how your direct dependencies interact with their transitive dependencies. If a direct dependency can call a vulnerable function in a transitive dependency, that vulnerability is marked as reachable. 3. **Filter unreachable vulnerabilities**: If a vulnerable function in a transitive dependency cannot be reached through any of your direct dependencies (based on the pre-computed call graph information), the CVE is marked as unreachable and can be deprioritized. The key insight is that pre-computed reachability leverages the fact that Endor Labs has already analyzed how open-source packages interact with their dependencies. By assuming your direct dependencies are fully reachable and using this pre-computed information, the analysis can determine which transitive dependency vulnerabilities could be reachable without needing to build your application or analyze your source code. ### Reachable vs Unreachable CVEs Based on the analysis: * **Unreachable CVEs**: If a vulnerable function in a transitive dependency cannot be reached through any of your direct dependencies (based on pre-computed call graph information), the CVE is marked as unreachable. These can be deprioritized, as the vulnerable code cannot be invoked through your dependency chain. * **Reachable CVEs**: If a vulnerable function in a transitive dependency can be reached through one or more of your direct dependencies, the vulnerability is flagged as *reachable*. For reachable CVEs, Endor Labs shows the list of function calls in your dependencies that may trigger the vulnerability. Pre-computed reachability assumes all direct dependencies are reachable, so if a direct dependency can call a vulnerable function in a transitive dependency, that vulnerability is marked as reachable. Pre-computed reachability focuses on analyzing dependency relationships rather than your application's source code usage. For the most precise assessment when builds are successful, [function-level reachability analysis](/scan/sca/reachability-analysis#function-level-reachability) analyzes your application's source code directly through full call graph generation to determine actual usage. Pre-computed reachability analyzes how your direct dependencies interact with transitive dependencies, but does not analyze direct calls to transitive dependencies from your application code. For complete coverage including direct usage of transitive dependencies, [function-level reachability analysis](/scan/sca/reachability-analysis#function-level-reachability) provides full analysis when builds are successful. ## When Pre-computed Reachability is Used Pre-computed reachability serves two distinct purposes: ### As a Fallback for Full Scans For full scans, pre-computed reachability automatically serves as a fallback when: * **Builds fail**: If your project build fails or encounters errors, pre-computed reachability ensures you still get reachability analysis rather than missing out entirely. * **Call graph generation isn't possible**: In cases where full call graph generation isn't available, pre-computed reachability provides valuable reachability insights. ### As an Option for Quick Scans For quick scans, you can proactively enable pre-computed reachability when you want reachability analysis without build requirements. This pragmatic approach provides vulnerability assessment based on manifest files alone, making it ideal for: * **Build-free analysis**: When you want reachability insights without setting up build environments or waiting for compilation. * **CI/CD pipelines**: In environments where you want reachability analysis without build dependencies. * **Large-scale scanning**: When scanning multiple repositories or projects, where build setup isn't practical. The philosophy behind pre-computed reachability is simple: don't let perfect get in the way of better. When full call graph analysis isn't possible or when you want a pragmatic approach without build requirements, pre-computed reachability ensures you still get actionable security insights rather than no analysis at all. ## Comparison with Other Reachability Analysis Types Pre-computed reachability complements Endor Labs' other reachability analysis capabilities: * **[Function-level reachability](/scan/sca/reachability-analysis#function-level-reachability)**: The most precise analysis that examines your application's source code directly through full call graph generation. This is the primary and preferred method when builds succeed, providing the highest accuracy for production applications. * **[Pre-computed reachability](/scan/sca/reachability-analysis/pre-computed-reachability)**: A pragmatic, manifest-based analysis that works without builds or source code access. Serves as an automatic fallback for full scans when builds fail, and can be enabled for quick scans when you want reachability analysis without build requirements. Focuses on transitive dependencies. Endor Labs automatically uses the best available analysis method for your situation. When full call graph generation is possible, it's used for maximum precision. When it's not, pre-computed reachability steps in as a reliable fallback, ensuring you always get actionable security insights. ## Limitations ### Direct Dependency Vulnerabilities Pre-computed reachability analysis is optimized for vulnerabilities in transitive/indirect dependencies, where it can leverage the analysis of how your direct dependencies interact with their dependencies. When full call graph generation is possible, [function-level reachability analysis](/scan/sca/reachability-analysis#function-level-reachability) provides more precise results by analyzing your application's source code directly. # Ruby Source: https://docs.endorlabs.com/scan/sca/ruby/index Learn how to implement Endor Labs in repositories with Ruby packages. Ruby is a widely used open-source programming language. Endor Labs supports scanning and monitoring of Ruby projects. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## Software prerequisites Before you begin, verify the following prerequisites: * All applications monitored by Endor Labs must be on Ruby versions 2.6 or higher. * A Gemfile or a `*.gemspec` file must be present in your Ruby project. * Make sure your repository includes one or more files with `.rb` extension. ## Build Ruby projects You can build your Ruby projects before running a scan. Building first creates the `Gemfile.lock` file. Ensure your repository has Gemfile and run the following command making sure it builds the project successfully. ```bash theme={null} bundler install ``` If the project is not built, endorctl will build the project during the scan and generate `Gemfile.lock`. If the repository includes a `Gemfile.lock`, endorctl uses this file for dependency resolution and does not create it again. ### Configure private RubyGems package repositories Endor Labs supports fetching and scanning dependencies from private RubyGems package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See [RubyGems package manager integrations](/integrations/package-managers/rubygems-private-package-manager) for more information on configuring private registries. ## Run a scan Perform a scan to get visibility into your software composition and resolve dependencies. ```bash theme={null} endorctl scan ``` You can perform the scan from within the root directory of the Git project repository, and save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan -o json | tee /path/to/results.json ``` You can sign in to the [Endor Labs user interface](https://app.endorlabs.com), click the **Projects** on the left sidebar, and find your project to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ## Understand the scan process Endor Labs looks for `Gemfile`, `*.gemspec`, and `Gemfile.lock` files to find and monitor the dependency activity. * A Gemfile is a configuration file used in Ruby projects to specify the required RubyGems (libraries or packages) for the project's dependencies. * A `*.gemspec` file is a RubyGems specification file used to define the metadata and dependencies for a RubyGem. * The `Gemfile.lock` file is automatically generated by Bundler. Refer to [Bundler documentation](https://bundler.io/guides/getting_started.html) for more information about getting started. If the `Gemfile.lock` is not present in your project, Endor Labs generates this file and stores it in a temp directory. Endor Labs deletes the file after extracting dependency information. Endor Labs' dependency resolution mechanism assesses multiple factors, including compatibility, stability, and availability, to determine the most suitable version for usage. Your Ruby project uses the resolved dependency version during build or execution. By utilizing the dependency graph, you can access significant information about the dependencies. This includes determining whether a dependency is direct or transitive, checking its reachability, verifying source availability, and more. The dependency graph provides a visual representation that allows you to examine the graphical details of these dependencies. ### Known limitations * Call graphs are not supported for Ruby projects. * If a dependency cannot resolve in the Gemfile, the build for that specific package may not succeed. The package may no longer exist in the Gem package manager. Other packages in the workspace are scanned. ## Troubleshoot errors * **Unresolved dependency errors**: The Gemfile is not buildable. Try running `bundler install` in the root project to debug this error. * **Resolved dependency errors**: A dependency version does not exist or cannot be found. The package may no longer exist in the repository. # Rust Source: https://docs.endorlabs.com/scan/sca/rust/index Learn how to implement Endor Labs in repositories with Rust packages. Rust is a software programming language widely used by developers. Endor Labs supports scanning and monitoring of Rust projects. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## System specifications for scan Make sure that you have a minimum system requirement specification of an 8-core processor with 32 GB RAM. Use a system equipped with either Mac OS X or Linux operating systems to perform the scans. ## Software prerequisites * Install the following prerequisites: * Package Manager Cargo - Any version * Rust - Any version, * Install Bazel version `5.x.x`, `6.x.x`, `7.x.x`, `8.x.x`, or `9.x.x` if your project uses Bazel. Bazel support requires aspects (`--use-bazel-aspects`). Endor Labs supports Bzlmod with Bazel aspects. See [Bazel](/scan/bazel) for more information. * Make sure your repository includes one or more files with `.rs` extension. * Install Rust using the latest [rustup](https://www.rust-lang.org/tools/install) tool. ## Build Rust projects Ensure your repository has `Cargo.toml` file and run the following command making sure it builds the project successfully. ```bash theme={null} cargo build ``` If the project is not built, endorctl will build the project during the scan and generate the `Cargo.lock` file. If the repository includes a `Cargo.lock` file, endorctl uses this file for dependency resolution and does not create it again. ## Scan Bazel projects To scan Rust projects that use Bazel, see [Bazel](/scan/bazel) for build instructions, supported rules, and scan commands. Bazel support for Rust requires aspects using `rules_rust` >= 0.40.0. Bzlmod is also supported. See [Bazel Aspects](/scan/bazel/bazel-aspects) for more information. ## Run a scan Perform a scan to get visibility into your software composition and resolve dependencies. ```bash theme={null} endorctl scan ``` You can perform the scan from within the root directory of the Git project repository, and save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan -o json | tee /path/to/results.json ``` Sign in to the [Endor Labs user interface](https://app.endorlabs.com), select **Projects** from the left sidebar, and find your project to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ## Understand the scan process Endor Labs resolves dependencies for the package version when it scans Rust projects. ### Resolving Dependencies Endor Labs leverages the Cargo.toml file in Rust and uses this file to build the package version using Cargo. Endor Labs uses the output from `cargo metadata` to resolve dependencies specified in Cargo.toml files and construct the dependency graph. ### Known Limitations * Call graphs are not supported for Rust projects. * Scanning Rust projects on the Microsoft Windows operating system is currently unsupported. ## Troubleshoot errors * **Host system check failure errors**: These errors occur when Rust is not installed or not present in the path variable. Install Rust and try again. # Scala Source: https://docs.endorlabs.com/scan/sca/scala/index Learn how to implement Endor Labs in repositories with Scala packages. Scala is a general-purpose and scalable programming language widely used by developers. Endor Labs supports the scanning and monitoring of Scala projects managed by sbt, Gradle, or Bazel. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## System specifications for scan Make sure that your system has a minimum 8-core processor with 32 GB RAM to successfully scan Scala projects. ## Software prerequisites * Install JDK versions between 11 and 25.0.3. * For JDK 8, see [Scan projects on JDK version 8](/scan/sca/java#scan-the-projects-on-jdk-version-8). * Make sure your repository includes one or more files with `.scala` or `.sc` extension. * Install sbt version 1.4 or higher if your project uses sbt. * For sbt versions lower than 1.4, install the [sbt-dependency-graph](https://github.com/sbt/sbt-dependency-graph) plugin, which is included by default in sbt 1.4 and later. * Ensure that the `project/build.properties` file specifies the required sbt version. * Install Gradle build system version 6.0.0 and higher, if your project uses Gradle. * To support lower versions of Gradle, see [Scan projects on older Gradle versions](/scan/sca/java#scan-projects-on-gradle-versions-between-4-7-and-6-0-0). * Install Bazel version `5.x.x`, `6.x.x`, `7.x.x`, `8.x.x`, or `9.x.x` if your project uses Bazel. Endor Labs supports Bzlmod with Bazel aspects. See [Bazel](/scan/bazel) for more information. * Your repository must include the appropriate build manifest file: * `build.sbt` for sbt projects. * `build.gradle` or `build.gradle.kts` for Gradle projects. * `WORKSPACE` or `MODULE.bazel` for Bazel projects. ## Build Scala projects Before initiating a scan with Endor Labs, ensure that your Scala projects build successfully. Also verify that packages exist in local package caches and build artifacts exist in their standard locations. Follow the guidelines to build projects using sbt, Gradle, or Bazel. ### Use Gradle To analyze your software built with Gradle, you must successfully build the software. To perform a quick scan, locate the dependencies in the local package manager cache. Ensure that the standard `$GRADLE_USER_HOME/caches` or `/User//.gradle/caches` exists and contains successfully downloaded dependencies. To perform a deep scan, generate the target artifact on the file system as well. To build your project with Gradle, use the following procedure: 1. To run a scan against a custom configuration, specify the Gradle configuration by setting an environment variable. ```bash theme={null} export endorGradleScalaConfiguration="" ``` When there is no configuration, endorctl uses `runtimeClasspath` by default. If neither the user-specified nor the default configuration exists in the project, endorctl falls back to the following configurations, in order: 1. `runtimeClasspath` 2. `runtime` 3. `compileClasspath` 4. `compile` If endorctl does not find the listed configurations in the project, it selects the first available configuration in alphabetical order. 2. Ensure that you can resolve the dependencies for your project without errors by running the following command: For Gradle wrapper: ```bash theme={null} ./gradlew dependencies ``` For Gradle: ```bash theme={null} gradle dependencies ``` 3. Run `./gradlew assemble` or `gradle assemble` to resolve dependencies and create an artifact for deep analysis. #### Override subproject level configuration In a multi-build project, if you set the environment variable `endorGradleScalaConfiguration=[GlobalConfiguration]`, endorctl uses the specified configuration for dependency resolution across all projects and subprojects in the hierarchy below. ```bash theme={null} \--- Project ':samples' +--- Project ':samples:compare' +--- Project ':samples:crawler' +--- Project ':samples:guide' +--- Project ':samples:simple-client' +--- Project ':samples:slack' +--- Project ':samples:static-server' +--- Project ':samples:tlssurvey' \--- Project ':samples:unixdomainsockets' ``` To override the configuration only for the `:samples:crawler` and `:samples:guide` subprojects, follow these steps: 1. Navigate to the root workspace, where you execute `endorctl scan`, and run `./gradlew projects` to list all projects and their names. 2. Run the following command at the root of the workspace: ```bash theme={null} echo ":samples:crawler=testRuntimeClasspath,:samples:guide=macroBenchMarkClasspath" >> .endorproperties ``` This creates a new file named `.endorproperties` in your root directory. This enables different configurations for the specified subprojects in the file. 3. Run `endorctl scan`. At this point, all other projects will adhere to the `GlobalConfiguration`. However, the `:samples:crawler` subproject will use the `testRuntimeClasspath` configuration, and the `:samples:guide` subproject will use the `macroBenchMarkClasspath` configuration. #### Configure private Gradle package repositories Endor Labs supports fetching and scanning dependencies from private Gradle package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See [Gradle package manager integrations](/integrations/package-managers/gradle-private-package-manager) for more information on configuring private registries. ### Use Bazel To scan Scala projects that use Bazel, see [Bazel](/scan/bazel) for build instructions, supported rules, and scan commands. Endor Labs supports Bzlmod with Bazel aspects using `rules_scala` >= 5.0.0. See [Bazel Aspects](/scan/bazel/bazel-aspects) for more information. ### Use sbt To analyze your software built with sbt, you must successfully build the software. * The standard `.sbt` cache must exist and contain all required dependencies for both quick and deep scans. * For deep scans, the build artifact must exist on the filesystem. * Make sure `sbt dependencyTree` runs successfully inside the project directory. 1. Run the following commands to build the project successfully. Ensure your repository has a `build.sbt` file. ```bash theme={null} sbt compile ``` ```bash theme={null} sbt projects ``` 2. Run endorctl scan. If your project includes both sbt and Gradle build systems, Endor Labs scans your project using only one build system to avoid scanning the same packages multiple times. When both are present, Gradle has higher priority for dependency resolution. ## Run a scan Use the following options to scan your repositories. Perform a scan after building the projects. ### Quick scan Run a quick scan to rapidly assess your dependencies using only the compiled code and cached packages and get quick visibility into your software composition. This scan won't perform reachability analysis to help you prioritize vulnerabilities. ```bash theme={null} endorctl scan --quick-scan ``` ### Deep scan Use the deep scan to perform dependency resolution, reachability analysis, and generate call graphs. You can do this after you complete the quick scan successfully. ```bash theme={null} endorctl scan ``` Use the following flags to save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan -o json | tee /path/to/results.json ``` During a deep scan, Endor Labs analyzes all private software dependencies in full by default if they have not been previously scanned. This is a one-time operation and will slow down initial scans, but won't impact subsequent scans. Organizations might not own some parts of the software internally and the related findings are not actionable by them. They can choose to disable this analysis using the flag `disable-private-package-analysis`. By disabling private package analysis, teams can enhance scan performance but may lose insights into how applications interact with first-party libraries. Use the following command flag to disable private package analysis: ```bash theme={null} endorctl scan --disable-private-package-analysis ``` You can sign in to the [Endor Labs user interface](https://app.endorlabs.com), click the **Projects** on the left sidebar, and find your project to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ## Understand the scan process Endor Labs scans Scala projects by executing sbt plugins and inspecting the `build.sbt` file to retrieve information about direct and transitive dependencies. * The `build.sbt` file is a configuration file used in Scala projects with sbt to define project settings, dependencies, and build tasks. This file provides the necessary configuration and instructions to sbt on resolving and managing project dependencies. * The sbt dependency graph plugin visualizes the dependencies between modules in a Scala project. * For packages built using Gradle, it uses Gradle and Gradle wrapper files to build packages and resolve dependencies. * Endor Labs supports EAR, JAR, RAR, and WAR files. Endor Labs analyzes information from both these methods to determine different components, binary files, manifest files, images, and more in the Scala codebase. It presents finding policy violations, identifies dependencies, and resolves them. Using Endor Labs, users can gain significant insights into the structure and relationships of their Scala project's dependencies. This aids in managing dependencies effectively, identifying potential issues, and ensuring a well-organized and maintainable codebase. ### How Endor Labs performs static analysis on the code Endor Labs performs static analysis based on the following factors: * Endor Labs creates call graphs for your package and combines them with the dependency call graphs to form a comprehensive call graph for the entire project. * Endor Labs performs an inside-out analysis of the software to determine the reachability of dependencies in your project. * The static analysis time may vary depending on the number of dependencies in the package and the number of packages in the project. ### Known limitations Software composition analysis for Scala is not validated on Microsoft Windows operating systems and may not work as expected. Scanning Scala projects on Windows requires PowerShell (`pwsh`). ## Troubleshoot errors Here are a few error scenarios that you can check for and attempt to resolve them. * **Host system check failure errors**: These errors occur if: * sbt is not installed or present in the path variable. Install sbt 1.4 or higher versions and try again. * The sbt version mentioned in the project or the `build.properties` file is lower than 1.4 and the `sbt-dependency-graph` plug-in is not installed. Install the `sbt-dependency-graph` plug-in and try again. * Java is not installed or not present in the PATH environment variable. Install Java and try again. See [Java documentation](https://www.oracle.com/java/technologies/downloads/) for more information. * The installed version of Java is lower than the required version. Install JDK versions between 11 and 25.0.3 and try again. * Java is installed but sbt or Gradle is not installed. In such cases, the dependency resolution may not be complete. * **Dependency graph errors**: Scala by default imports `MiniDependencyTreePlugin`, which is a mini version of the `sbt-dependency-graph` plugin and supports only the `dependencyTree` command. To get complete features of the `sbt-dependency-graph` plugin, add `addDependencyTreePlugin` to your `project/plugins.sbt` file and run the scan again. See [Scala documentation](https://eed3si9n.com/sbt-1.4.0#:~:text=sbt%2Ddependency%2Dgraph%20is%20in%2Dsourced) for details. # Scanning strategies Source: https://docs.endorlabs.com/scan/sca/scanning-strategies/index Learn strategies to best scan your projects with Endor Labs. As you deploy Endor Labs in your environment, it's important for your team to understand key scanning strategies. ## Set a default branch The findings, metrics, and data shown on the dashboard and the project listing page are based on scanning the default branch, which is also known as the main context. **Important recommendation** If you are scanning multiple branches, it is essential to select and set one as the default branch. When performing the endorctl scan, use the flag `--as-default-branch` to designate a project branch as the default branch and view its findings. ```bash theme={null} endorctl scan --as-default-branch ``` If you do not set the flag `as-default-branch`, the first branch you scan is automatically considered as the default branch. After a scan, if you switch the default branch to another using `--as-default-branch`, scans from the previous branches are erased, and their findings will no longer be available. You do not need to set a default branch if you are using the Endor Labs GitHub App or not scanning multiple branches. **Tagged versions** The `--as-default-branch` flag marks whatever branch, tag, or commit you scan as the default version for the project. If you scan and mark a new tag as the default version, the previously monitored version is removed from the monitored versions dropdown and its scan history is no longer available. ## Testing and monitoring different versions of your code Across the software engineering lifecycle it is important that continuous testing is separated from what is monitored and reported on regularly. Often, engineering organizations want to test each and every change that enters a code base, but if security teams reported on each test they would quickly find themselves overwhelmed with noise. Endor Labs enables teams to separate what should be reported on relative to what should be tested but not reported on. Endor Labs allows teams to select reporting strategies for their software applications when integrated into CI/CD pipelines. Here are the primary scanning and reporting strategies: * **Reporting on the default branch** - All pull request commits are tested and all pushes or merges to the default branch are reported on and monitored by security and management teams. * **Reporting on the latest release** - All reporting and monitoring is performed against tagged release versions. This requires each team have a mature release tagging strategy. ### How to deploy a strategy for reporting The `endorctl scan` command by default will continuously monitor a version of your code for new findings such as unmaintained, outdated or vulnerable dependencies in the bill of materials for a package. To test a version of your code without monitoring and reporting on it, use the flag `--pr` or environment variable `ENDOR_SCAN_PR` as part of your scan. When adopting a strategy such as reporting on the default branch, you will want to run any push or merge event to the default branch without the `--pr` flag and run any pull\_request or merged\_request event with the `--pr` flag. This allows you to test changes before they have been approved and report what has been merged to the default branch as your closest proxy to what is in production. Let's use the following GitHub Actions workflow as an example! In this workflow any push event will be scanned without the `--pr` flag but any pull\_request event is scanned as a point in time test of that specific version of your code. The examples pin the Endor Labs GitHub Action to release `v1.1.12`. To use a newer release, copy the **Use in your workflow** reference from **Latest GitHub Action Release** in [Secure GitHub Actions with immutable commit SHA](/setup-deployment/ci-cd/scan-with-github-actions#secure-github-actions-with-immutable-commit-sha). ```yaml expandable theme={null} name: Endor Labs Scan on: push: branches: [main] pull_request: branches: [main] jobs: scan: permissions: security-events: write # Used to upload sarif artifact to GitHub contents: read # Used to check out a private repository but actions/checkout. actions: read # Required for private repositories to upload sarif files. GitHub Advanced Security licenses are required. id-token: write # Used for keyless authentication to Endor Labs runs-on: ubuntu-latest steps: - name: Checkout Repository uses: actions/checkout@v3 - name: Setup Java uses: actions/setup-java@v3 with: distribution: 'microsoft' java-version: '17' - name: Build Package run: mvn clean install - name: Endor Labs Scan Pull Request if: github.event_name == 'pull_request' uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' pr: true sarif_file: 'findings.sarif' pr_baseline: $GITHUB_BASE_REF - name: Endor Labs Reporting Scan if: github.event_name == 'push' uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' pr: false sarif_file: 'findings.sarif' - name: Endor Labs Testing Scan if: github.event_name == 'pull_request' uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' pr: true sarif_file: 'findings.sarif' - name: Upload findings to github uses: github/codeql-action/upload-sarif@v3 with: sarif_file: 'findings.sarif' ``` #### Scanning detached refs In some CI/CD based environments, each time code is pushed to the default branch the exact commit SHA is checked out as a detached Git Reference. This is notably the case with Jenkins, CircleCI and GitLab Pipelines. In these scenarios, on push or merge events Endor Labs must be told that the reference should be monitored as the default branch. You can do this with the `--detached-ref-name` flag or `ENDOR_SCAN_DETACHED_REF_NAME` environment variable. You should also couple this flag with the `--as-default-branch` flag or `ENDOR_SCAN_AS_DEFAULT_BRANCH` environment variable. This allows you to set this version of code as a version that should be monitored as well as define the name associated with the branch. This strategy may be used for both a strategy reporting on the default branch on push events and a strategy reporting on tag creation event for that version of code. You can see in the below GitLab Pipelines example defining the logic to manage a detached reference on GitLab. ```yaml theme={null} - if [ "$CI_COMMIT_REF_NAME" == "$CI_DEFAULT_BRANCH" ]; then export ENDOR_SCAN_AS_DEFAULT_BRANCH=true; export ENDOR_SCAN_DETACHED_REF_NAME="$CI_COMMIT_REF_NAME"; else export ENDOR_SCAN_PR=true; fi ``` You can find the full GitLab pipelines reference below: If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ```yaml expandable theme={null} Endor Labs Dependency Scan: stage: Scan image: node # Modify this image to align with the build tools necessary to build your software packages dependencies: [] variables: ENDOR_ENABLED: "true" ENDOR_ALLOW_FAILURE: "true" ENDOR_NAMESPACE: "demo" ENDOR_SCAN_PATH: "." ENDOR_ARGS: | --show-progress=false --detached-ref-name=$CI_COMMIT_REF_NAME --output-type=summary --exit-on-policy-warning --dependencies --secrets --git-logs before_script: - npm install yarn script: - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl; - echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c; if [ $? -ne 0 ]; then echo "Integrity check failed"; exit 1; fi - chmod +x ./endorctl - if [ "$DEBUG" == "true" ]; then export ENDOR_LOG_VERBOSE=true; export ENDOR_LOG_LEVEL=debug; fi - if [ "$CI_COMMIT_REF_NAME" == "$CI_DEFAULT_BRANCH" ]; then export ENDOR_SCAN_AS_DEFAULT_BRANCH=true; export ENDOR_SCAN_DETACHED_REF_NAME="$CI_COMMIT_REF_NAME"; else export ENDOR_SCAN_PR=true; fi - ./endorctl scan ${ENDOR_ARGS} rules: - if: $ENDOR_ENABLED != "true" when: never - if: $CI_COMMIT_TAG when: never - if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH && $ENDOR_FEATURE_BRANCH_ENABLED != "true" when: never - if: $ENDOR_ALLOW_FAILURE == "true" allow_failure: true - if: $ENDOR_ALLOW_FAILURE != "true" allow_failure: false ``` ### Implementing baseline scans One of the common concerns software development teams have when adopting preventative controls is ownership of issues. Often, software has accrued significant technical debt, or new vulnerabilities arise that don't directly impact their changes. Security teams want to have all known issues addressed while the development teams are focused on fixing issues or delivering core business value. They can't be hindered each time a new issue impacts their entire code base. To prevent new issues from entering the environment, security teams sometimes set policies that may break the build or return a non-zero exit code that can fail automated tests. This creates friction as there is no context around what changes a developer is responsible for versus what technical debt exists in a codebase on that day. Establishing a baseline of what issues already exist in a software project and what issues may occur because of new updates is crucial to enabling preventative control adoption. ## Accelerating preventative control adoption with CI baselines The high-level steps to establish and measure policies against a baseline scan are as follows: 1. Establish a baseline scan of your default branch or any other branch that undergoes regular testing 2. Integrate baseline scans into your automated workflows 3. Evaluate policy violations within the context of the branches to which you routinely merge ### Implementing baseline scan into your program Development teams often have different delivery strategies. Some merge changes to a default branch. Others merge to a release branch that is then released to their environment. While these strategies differ across organizations, a baseline scan must exist to measure against attribute ownership. To establish a baseline scan, your team must perform regular scans on the branch to which you merge. This often means that you scan each push of your default branch to monitor your environment and you test each pull request using the `--pr` and `--pr-baseline` flags. The `--pr` flag is a user's declaration that they are testing their code as they would in a CI pipeline. The `--pr-baseline` flag tells Endor Labs which Git reference to measure any changes. For this example, we will use the default branch as a merging strategy. In this strategy, you'll want to scan the default branch on each push event to re-establish your baseline. You'll also want to establish your CI baseline as the default branch. The following GitHub workflow illustrates this strategy. The examples pin the Endor Labs GitHub Action to release `v1.1.12`. To use a newer release, copy the **Use in your workflow** reference from **Latest GitHub Action Release** in [Secure GitHub Actions with immutable commit SHA](/setup-deployment/ci-cd/scan-with-github-actions#secure-github-actions-with-immutable-commit-sha). ```yaml expandable theme={null} name: Endor Labs Scan on: push: branches: [main] pull_request: branches: [main] jobs: scan: permissions: security-events: write # Used to upload sarif artifact to GitHub contents: read # Used to check out a private repository but actions/checkout. actions: read # Required for private repositories to upload sarif files. GitHub Advanced Security licenses are required. id-token: write # Used for keyless authentication to Endor Labs runs-on: ubuntu-latest steps: - name: Checkout Repository uses: actions/checkout@v3 - name: Setup Java uses: actions/setup-java@v3 with: distribution: 'microsoft' java-version: '17' - name: Build Package run: mvn clean install - name: Endor Labs Scan Pull Request if: github.event_name == 'pull_request' uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' pr: true sarif_file: 'findings.sarif' pr_baseline: $GITHUB_BASE_REF - name: Endor Labs Reporting Scan if: github.event_name == 'push' uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' pr: false sarif_file: 'findings.sarif' - name: Endor Labs Testing Scan if: github.event_name == 'pull_request' uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' pr: true sarif_file: 'findings.sarif' - name: Upload findings to github uses: github/codeql-action/upload-sarif@v3 with: sarif_file: 'findings.sarif' ``` Each CI environment includes default environment variables that you can use to reference CI baselines in a template. See your CI providers' documentation on default environment variables to determine the most suitable option for your requirements. * [See the GitHub Actions documentation for GitHub default variables.](https://docs.github.com/en/actions/learn-github-actions/variables) * [See the GitLab CI/CD documentation for the GitLab default variables.](https://docs.gitlab.com/ee/ci/variables/) ## Understand SARIF files SARIF (Static Analysis Results Interchange Format) is an OASIS standard format for reporting static analysis results. This standardized format allows you to: * Integrate with multiple platforms: Upload results to GitHub Security, Azure DevOps, or other tools that support SARIF. * Consolidate findings: Combine results from different security tools in a unified format. * Automate workflows: Process and act on security findings programmatically. * Track remediation: Monitor the status of security issues over time. Endor Labs generates SARIF files that contain detailed information about security findings, dependency issues, and other analysis results from your scans. ### SARIF file structure A SARIF file contains multiple key components: * **Runs**: Each scan execution creates a run with metadata about the scan. * **Results**: Individual findings with details about dependency vulnerabilities, SAST findings, and secrets. * **Rules**: Descriptions of the checks that were performed. * **Artifacts**: Information about the files and dependencies that were analyzed. ### Generate SARIF output using endorctl SARIF files standardize security findings, enabling CI/CD integration, unified dashboards, and compliance reporting. They provide PR-level feedback, support long-term monitoring, and preserve historical data for auditing and tool migration. To generate SARIF output with Endor Labs, use the `--sarif-file` or `-s` flag with the endorctl scan command: ```bash theme={null} endorctl scan --namespace= --sarif-file findings.sarif ``` You can specify additional scan options when generating SARIF output, for example to include dependency scanning and git history secrets detection: ```bash theme={null} endorctl scan --sarif-file findings.sarif --dependencies --secrets --git-logs ``` ### Upload SARIF files to GitHub GitHub Security supports SARIF file uploads, allowing you to view Endor Labs findings directly in your repository's Security tab. You can upload SARIF files automatically using the GitHub App (Pro), through GitHub Actions, or manually. #### Automatic upload using GitHub App (Pro) When you configure Endor Labs GitHub App (Pro) with a GHAS SARIF exporter, findings are automatically exported and uploaded to GitHub after each scan. See [Export findings to GitHub Advanced Security](/integrations/data-exporters/export-to-ghas) for detailed setup instructions. #### Automated upload using GitHub Actions Use the following GitHub Actions workflow step to automatically upload SARIF files. ```yaml theme={null} - name: Upload SARIF file to GitHub uses: github/codeql-action/upload-sarif@v3 with: sarif_file: 'findings.sarif' ``` #### Manual upload via GitHub To manually upload a SARIF file to GitHub: 1. Navigate to your GitHub repository. 2. Go to **Security** > **Code scanning** > **Upload SARIF**. 3. Select your SARIF file and upload it. ### Endor-specific SARIF extensions Endor Labs extends the standard SARIF format with custom fields that provide additional context for vulnerability analysis and remediation. These properties are included in the `properties` field of each SARIF result. The following fields are available in SARIF results generated by Endor Labs: * `action-policies-triggered`: List of action policies triggered by this finding. * `categories`: List of categories the finding belongs to. * `cvss-score`: Common Vulnerability Scoring System (CVSS) score, ranging from 0.0 to 10.0. * `cvss-vector`: CVSS vector string describing the characteristics of the vulnerability. * `cvss-version`: The version of the CVSS score used. * `epss-percentile-score`: EPSS percentile score, showing how severe the vulnerability is compared to others. * `epss-probability-score`: Exploit Prediction Scoring System (EPSS) probability score, indicating likelihood of exploitation. * `explanation`: Detailed explanation of the finding and its implications. * `finding-url`: URL to view the finding in Endor Labs. * `finding-uuid`: Unique identifier for the finding. * `impact-score`: Custom impact score assigned to the finding. * `project-uuid`: Unique identifier for the project where the finding was discovered. * `remediation`: Recommended steps to fix or mitigate the finding. * `tags`: List of tags associated with the finding, used for categorization and filtering. Here are examples of SARIF output for SCA, secrets, and SAST findings, including Endor-specific extensions. ```json theme={null} { "results": [ { "ruleId": "SCA-Vulnerability", "kind": "fail", "level": "error", "message": { "text": "CVE-2021-44228 in org.apache.logging.log4j:log4j-core@2.14.1 (maven) — upgrade to 2.17.1 or later." }, "locations": [ { "physicalLocation": { "artifactLocation": { "uri": "pom.xml" }, "region": { "startLine": 42 } } } ], "properties": { "action-policies-triggered": ["block-critical-vulns"], "categories": ["dependency", "security"], "cvss-score": 10.0, "cvss-vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H", "cvss-version": "V3_1", "epss-percentile-score": 0.97, "epss-probability-score": 0.97576, "explanation": "This version of log4j-core contains CVE-2021-44228, also known as Log4Shell. This is a critical remote code execution vulnerability that allows attackers to execute arbitrary code by controlling log message content.", "finding-url": "https://app.endorlabs.com/findings/abc123", "finding-uuid": "abc123-def456", "impact-score": 10.0, "project-uuid": "proj-789", "remediation": "Upgrade log4j-core to version 2.17.1 or later. If immediate upgrade is not possible, set the JVM parameter -Dlog4j2.formatMsgNoLookups=true as a temporary mitigation.", "tags": ["CVE-2021-44228", "log4shell", "critical", "rce"] } } ] } ``` ```json theme={null} { "results": [ { "ruleId": "AWS Access Token", "message": { "text": "Invalid AWS Access Token: ID #3da668" }, "fullDescription": { "text": "Invalid secrets should be audited for suspicious activity and ignored." }, "help": { "text": "Inspect any service logs to determine if the exposed secret has been used for suspicious activity.\n\nIf you'd like to ignore this issue add the comment \"endorctl:allow\" to the secret location in your code.\n" }, "shortDescription": { "text": "Invalid AWS Access Token: ID #3da668" }, "properties": { "finding-url": "https://app.endorlabs.com/findings/secret-456", "finding-uuid": "secret-456-def", "project-uuid": "proj-789", "security-severity": "1.0", "tags": [ "INVALID_SECRET", "NORMAL", "POLICY" ] } } ] } ``` ````json theme={null} { "results": [ { "level": "note", "locations": [ { "physicalLocation": { "artifactLocation": { "uri": "BackendServer/middlewares/validateToken.js" }, "region": { "startLine": 77 } } } ], "message": { "text": "Problem:\nHardcoded JWT secret or private key was found. Hardcoding secrets like JWT signing keys poses a significant security risk. If the source code ends up in a public repository or is compromised, the secret is exposed. Attackers could then use the secret to generate forged tokens and access the system. Store it properly in an environment variable.\n\nSolution:\nHere are some recommended safe ways to access JWT secrets:\n- Use environment variables to store the secret and access it in code instead of hardcoding. This keeps it out of source control.\n- Use a secrets management service to securely store and tightly control access to the secret. Applications can request the secret at runtime.\n- For local development, use a .env file that is gitignored and access the secret from process.env.\n\nsample code snippet of accessing JWT secret from env variables\n```\nconst token = jwt.sign(payload, process.env.SECRET, { algorithm: 'HS256' });\n```\n" }, "properties": { "explanation": "The rule detects the use of hardcoded JWT secrets or private keys in JavaScript code. Hardcoding secrets like JWT signing keys poses a significant security risk because if the source code is exposed, the secret is compromised. This allows attackers to generate forged tokens, potentially gaining unauthorized access to systems and sensitive data. The impact is high because it directly affects the confidentiality and integrity of the application.", "finding-url": "https://app.endorlabs.com/findings/sast-789", "finding-uuid": "sast-789-ghi", "impact-score": 8.7, "project-uuid": "proj-789", "remediation": "To remediate the use of hardcoded JWT secrets, avoid embedding secrets directly in the source code. Instead, use environment variables to store secrets securely and access them in your code. For example, in JavaScript, you can use `process.env.SECRET` to access the secret stored in an environment variable:\n\n```javascript const token = jwt.sign(payload, process.env.SECRET, { algorithm: 'HS256' }); ``\n\nAdditionally, consider using a secrets management service to securely store and manage access to secrets. For local development, use a `.env` file that is gitignored to prevent it from being included in version control.", "tags": [ "A07:2021", "Identification-and-Authentication-Failures", "OWASP-Top-10", "SANS-Top-25" ] }, "ruleId": "Use of hard-coded credentials in JWT" } ] } ```` # Endor scores Source: https://docs.endorlabs.com/scan/sca/scores/index Understand how packages and AI Models are scored in Endor Labs. Endor Labs collects and analyzes a large amount of information about open-source packages and uses it to compute scores. * Every open-source package is scored across different dimensions that capture both security and operation aspects of a risk. * Every AI model is scored on a multidimensional scoring system grouped into four main categories: security, activity, popularity, and operational integrity. Each category's Endor score represents the average of all contributing factors within that category. See [View dependency details](/inventory-insights/dependencies#view-dependency-details) to check Endor Scores for a dependency in the Endor Labs user interface. See [Package scores](/scan/sca/scores/repository-scores) for more information on package scores. # Activity score factors Source: https://docs.endorlabs.com/scan/sca/scores/repository-scores/activity-score-factors/index Activity scores indicate the level of activity associated with a repository. Activity information is based on metadata gathered from a code hosting and version control system such as GitHub. Higher levels of activity can mean that the repository is well maintained and will continue to be in the future. The following factors have a positive contribution to the activity score: * Activity from corporate affiliated accounts indicates that the project can have reliable backing and support. * Activity from reputable accounts indicates that the repository is well-maintained. An account is considered reputable if it participates in multiple open-source projects and has a high rating on a source control system such as GitHub. * Consistent and continuous commit activity over longer periods of time indicates that the project is active. * The repository has frequent releases, indicating a commitment to maintaining and supporting the codebase. * Activity in the form of comments on issues shows there is engagement in the project. * A high ratio of issues opened by external contributors indicates that the project is active. * More issues being closed than opened indicates that the project is active. * The repository keeps releasing updates to earlier release trains. This is a sign of a commitment to maintaining and supporting the users of the project. * When a repository belongs to an organization, there is a lower risk of it getting abandoned in the future. * Recent issue and commit activity means the project is active. * Configuring topics is an indication that the repository is well-maintained. The following factors have a negative contribution to the activity score: * Archived repositories are not active and have a low score. * A high ratio of rejected pull requests indicates that the project may not be actively developed. * The lack of recent issue activity may indicate that the project is not actively used. * Notably more pull requests being submitted than merged indicates that the project may not be maintained. * The repository does not have any recent releases. This could mean that it is not actively maintained. * When a repository is personal, there is a higher risk of it getting abandoned in the future. * If the majority of the repository's activity comes from a small number of accounts, the project could be at risk if these accounts cannot continue their contributions. # Code quality score factors Source: https://docs.endorlabs.com/scan/sca/scores/repository-scores/code-quality-score-factors/index Code quality scores provide a view of code quality and adherence to best practices in a repository. Code quality information is based on metadata gathered from a code hosting and version control system such as GitHub and from the source code in the repository. The following factors have a positive contribution to the code quality score: * Activity from bot accounts shows that the project is using automation for some development tasks. * The repository has reached 1.0 release status, indicating the first major release milestone and is a sign of maturity. * The project includes test code. * Attaching labels to issues allows for better tracking of issue activity in the project. * The repository has multiple files that cover basic operational aspects of the project and this shows a strong emphasis on best practices. * A large fraction of the commits in this repository are verified; this shows that security best practices are followed. * Pull requests from dependency management bot accounts indicate that the project is using automation to keep its dependencies up to date. * Attaching labels to pull requests helps organize the development activity in the project. * Pull requests from bot accounts indicate that the project is using automation for development tasks. * A large fraction of the commits in this repository is associated with a pull request. This shows that development best practices are followed. * The repository has released signed artifacts which is a sign of mature security operations. * The use of continuous integration is a sign of good developer practices. * Using GitHub templates to manage issues shows that the development work in the repository is well-organized. * The repository includes badges. * Displaying the Code Coverage badge means that the repository is using code coverage tools in its development process. * Displaying the Core Infra Best Practices badge means that the repository has met a number of best practices requirements. * The repository includes documentation making it easier to understand and use. * The repository has files that cover basic operational aspects of the project and this shows an emphasis on best practices. * The repository uses CI and a high fraction of commits pass the CI checks which is a sign of good code quality. * Displaying the OSSF scorecards badge means that the repository strives to meet the OSSF scorecard checks. The following factors have a negative contribution to the code quality score: * The package has many instances of likely incorrect code that is associated with coding issues and potential bugs. * The package has many instances of questionable code warnings that are associated with coding issues and potential bugs. * The project has a high number of indirect dependencies compared to the number of direct dependencies; this additional code increases the cost of building the project and its supply chain risk. * The repository has many major releases in a short amount of time. This is a sign of high churn and potential instability. * Packages where the package manager license information does not agree with the license information found in the code require additional review. * Packages with multiple licenses require extra effort to determine their exact license status. * Multiple unpinned dependencies can materially increase the risk of a codebase since packages can be updated at any moment. * Many unreachable direct dependencies unnecessarily increase the size of the codebase and the cost of building it. * The project does not have an automated build system. * The repository does not have any of the files that typically explain the basic operational aspects of the project. This may be an indication that the project is not well-maintained. * Packages or source code without license information or a restrictive license can create operational risk. * The release is old and has been superseded by multiple newer releases. It should not be used. * The repository has releases that do not follow the SemVer standard. This goes against best practices. * When a repository contains binary files, it is harder to analyze and assess its functionality and risks. * Lack of access to the source code of the project dramatically limits visibility in its quality and adherence to best practices. * The repository has an unusually fast first release. # Package scores Source: https://docs.endorlabs.com/scan/sca/scores/repository-scores/index Understand how packages are scored in Endor Labs. Scores provide a high-level, easy-to-understand metric of how well a package does based on factors such as security, activity, popularity, and code quality. Endor Labs scores are categorized into: * **Security**: Indicates the number of security-related issues a package may have such as known vulnerabilities, following security best practices when developing code, and the results of static code analysis. Packages with lower security scores can be expected to have many security-related issues when compared with packages with higher scores. See the [factors affecting the security score](/scan/sca/scores/repository-scores/security-score-factors) for more details. * **Activity**: Indicates the level of development activity for a package as observed through the source code management system. Packages with higher activity scores will be more active and presumably better maintained when compared to packages with a lower activity score. See the [factors affecting the activity score](/scan/sca/scores/repository-scores/activity-score-factors) for more details. * **Popularity**: Indicates how widely a package is used in its ecosystem by tracking both source code management system metrics (for example, the number of stars in GitHub), as well as counting how many other packages import it. A package with a high popularity score indicates that it is used widely. See the [factors affecting the popularity score](/scan/sca/scores/repository-scores/popularity-score-factors) for more details. * **Code Quality**: Indicates how well the package complies with best practices for code development and includes the results of static code analysis of that package's source code. A package with a higher quality score has fewer code issues. See the [factors affecting the code quality score](/scan/sca/scores/repository-scores/code-quality-score-factors) for more details. ## Input data for score calculation For calculating scores of vulnerabilities, Endor Labs performs score computation for the following entity types: * **Repository score** - A repository has a score that captures overall repository activity and properties that span multiple versions of the code. * **Repository version score** - A repository version has a score that captures details that are specific to a version of the code. * **Package version score** - A package version that captures the details that are specific to a package version. The scoring algorithm considers the following input parameters while calculating the scores: * Data from a version control system such as Git that provides information about files, versions, and their contents. * Data from a source code management system such as GitHub that provides information about the development activities on a project like issues, pull requests, and more. * Data from Package managers that provide information about the properties of a package, for example, license, releases, and metadata like the number of stars. * Data from Vulnerabilities that provide information about known security issues in a package. * Data from Static code analysis tools that provide information about specific issues in the source code of the package. ### Score range The scores for each category range between 0 and 10. For example, a score of 5 indicates inconclusive analysis and the package is neutral. A score higher than 5 indicates that the package has more positive factors than negative ones, while a score lower than 5 indicates negative factors. A score of 10 indicates that the package meets all the positive conditions, while a score of 0 indicates that a package meets all negative conditions. # Popularity score factors Source: https://docs.endorlabs.com/scan/sca/scores/repository-scores/popularity-score-factors/index Popularity scores indicate how popular is the repository. Popularity information is based on metadata gathered from a code hosting and version control system such as GitHub. Popular repositories are more likely to be maintained. The following factors have a positive contribution to the popularity score: * Many reputable contributors affiliated with the project indicates that the project is reliable. An account is considered reputable if it participates in multiple open-source projects and has a high rating on GitHub. * The project includes many stars, indicating an interest in the project. * Having subscribers indicates interest in the project. * The project includes a high number of subscribers. * The repository includes a high number of dependent projects. * The repository includes many forks. * Some released artifacts of the repository are downloaded many times, indicating the project is popular. The following factors have a negative contribution to the popularity score: * Low fork count may indicate a lack of interest in the project. * Few subscribers may mean a lack of interest in the project. * Few stars may mean a lack of interest in the project. # Security score factors Source: https://docs.endorlabs.com/scan/sca/scores/repository-scores/security-score-factors/index Security scores indicate the level of compliance with security best practices as well as vulnerability information for the repository that includes open and fixed vulnerabilities. Vulnerability information is based on `OSV.dev` data and Endor Lab's vulnerability database. The following factors have a positive contribution to the security score: * Critical and high severity vulnerabilities were discovered in the past in the repository but have now been fixed. This indicates that the code base is properly maintained. * A `SECURITY.md` file highlighting security-related information is a sign of repository maturity. * A high volume of commits related to vulnerabilities may indicate that the project has many security issues but also that they are actively being addressed. A commit is considered vulnerability-related if it mentions a CVE in its commit message. * No vulnerabilities ever discovered in a repository indicate that there are no known security issues in the codebase. * Recently fixed vulnerabilities indicate that the repository has lower security risk and is well maintained. The following factors have a negative contribution to the security score: * The package has high activity from invalid accounts. * The package calls any of the following sensitive APIs more often than an average package. * Access to environment information like environment variables, user and host names. Some of this information may be security sensitive, such as environment variables with API keys. * Read or write access to the file system. This can be dangerous in combination with user-provided input, for example, lead to path traversal vulnerabilities. * Start of operating system processes. This can be dangerous in combination with user-provided input, as it can lead to command or parameter injection vulnerabilities. * Dynamic programming techniques like introspection, reflection or dynamic code execution through `eval()` type of functions or script engines. * Network functions, for example, to open connections or listen for incoming connection requests. This can be dangerous in combination with user-provided input, for example, lead to data leakage or the load of data from untrusted sources. * Cryptographic or encoding/decoding functions. Depending on the specific functions used and the data being processed, export control regulations may apply to downstream users. * The package contains code patterns or shows behaviors that are known to be used by malware. While this is not a guarantee that the package is malicious, a review of the related code is recommended. * A high fraction of critical vulnerabilities among the discovered vulnerabilities indicates an elevated security risk and potentially systematic security issues with the codebase. * A high fraction of high-fix priority vulnerabilities among the discovered vulnerabilities indicates an elevated security risk and that the repository needs immediate maintenance. A vulnerability is considered a high priority based on our analysis. * A high fraction of high severity or critical vulnerabilities among the discovered vulnerabilities indicates an elevated security risk and potentially systematic security issues with the codebase. * Taking more time to fix critical vulnerabilities discovered in a repository indicates a lack of regular maintenance. The analysis only considers vulnerabilities associated with this repository and not its dependencies. * A high fraction of releases with high severity vulnerabilities indicates an elevated security risk and potentially systematic security issues with the codebase. * The package has many unmerged vulnerability-related pull requests. This means that the project is not actively maintained and may have security issues. * The repository includes recently discovered vulnerabilities, indicating that the repository's security risk is increasing. * A high number of critical or unfixed vulnerabilities discovered in a repository indicates an elevated security risk and potentially systematic security issues with the codebase. # Swift/Objective-C Source: https://docs.endorlabs.com/scan/sca/swift-objective-c/index Learn how to implement Endor Labs in repositories with CocoaPods and Swift Package Manager (SwiftPM) packages. CocoaPods, SwiftPM, and Bazel are widely adopted tools for managing Swift and Objective-C projects. CocoaPods simplifies integration through `Podfile` declarations and automated installation, while SwiftPM manages dependencies through the `Package.swift` manifest. Endor Labs supports all three systems to help secure your applications. Using Endor Labs, application security engineers and developers can: * Scan their software for potential security issues and violations of organizational policy. * Prioritize vulnerabilities in the context of their applications. * Understand the relationships between software components in their applications. ## Software prerequisites Before you begin, verify the following prerequisites: * All applications monitored by Endor Labs must be on CocoaPods versions 0.9.0 or higher, or Swift Package Manager versions 5.0.0 or higher. * A `Podfile` and a `Podfile.lock` must be present in your CocoaPods project. * A `Package.swift` must be present in your SwiftPM project. * Install Bazel version `5.x.x`, `6.x.x`, `7.x.x`, `8.x.x`, or `9.x.x` if your project uses Bazel. Endor Labs supports Bzlmod with Bazel aspects. See [Bazel](/scan/bazel) for more information. * Your repository must include one or more files with `.swift`, `.h`, or `.m` extension. * Install the Swift toolchain on the system running the scan for SwiftPM projects. To verify the installation, run the `swift --version` command. * Your repository must include the appropriate build manifest file: * `Podfile` and `Podfile.lock` for CocoaPods projects. * `Package.swift` for SwiftPM projects. * `WORKSPACE` or `MODULE.bazel` for Bazel projects. ## Build CocoaPods projects If the `Podfile.lock` is not present in your repository, run the following command to create the `Podfile.lock` for your Podfile. ```bash theme={null} pod install ``` ## Scan Bazel projects To scan Swift projects that use Bazel, see [Bazel](/scan/bazel) for build instructions, supported rules, and scan commands. Endor Labs supports Bzlmod with Bazel aspects using `rules_swift` >= 2.0.0. See [Bazel Aspects](/scan/bazel/bazel-aspects) for more information. ## Run a scan Perform a scan to get visibility into your software composition and resolve dependencies. ```bash theme={null} endorctl scan ``` You can perform the scan from within the root directory of the Git project repository, and save the local results to a *results.json* file. The results and related analysis information are available on the Endor Labs user interface. ```bash theme={null} endorctl scan -o json | tee /path/to/results.json ``` Sign in to the [Endor Labs user interface](https://app.endorlabs.com), select **Projects** from the left sidebar, and find your project to review its results. If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. ## Understand the scan process for CocoaPods projects Endor Labs looks for the `Podfile` and `Podfile.lock` files to discover the dependencies used by an application. * A `Podfile` is a configuration file used in CocoaPods projects to specify the required libraries or packages for the project's dependencies. * A `Podfile.lock` file is a CocoaPods specification file used to define the metadata and dependencies. To successfully discover Swift and Objective-C dependencies, both `Podfile` and `Podfile.lock` files must be present in your project for each Podfile. ## Understand the scan process for SwiftPM projects Endor Labs scans SwiftPM projects by locating the `Package.swift` manifest file, which defines the Swift package's dependencies, targets, and metadata. Version-specific manifest files using the format `Package@swift-.swift`, for example `Package@swift-5.7.swift`, are also supported. ### Configure private SwiftPM package repositories Endor Labs supports fetching and scanning dependencies from private Swift package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See [Swift package manager integrations](/integrations/package-managers/swift-private-package-manager) for more information on configuring private registries. ## Known limitations * Call graphs aren't supported for Swift and Objective-C projects, including CocoaPods, SwiftPM, and Bazel. * If a `Podfile.lock` file isn't present, Endor Labs skips analyzing the project and presents a warning that it skipped the package. # Enable auto detection Source: https://docs.endorlabs.com/scan/scan-profiles/auto-detect-toolchains/index Learn how to automatically detect toolchains used in your repository. The system can automatically detect toolchains required for your projects based on the manifest files present in your repository. Auto detection is supported for Java, Python, Go and .NET(C#) projects. Only the Long Term Support (LTS) versions of the toolchains are supported in auto detection. See the [Toolchain support matrix](/scan/scan-profiles/build-tools#toolchain-support-matrix) for a complete list of supported toolchain versions for auto detection. ### How auto detection works Endor Labs begins auto detection by scanning your project repository to locate manifest files and identify the languages used in your project. Based on the results, it runs language specific detectors to extract version information. Each detector operates independently and follows a consistent process. It reviews the associated manifest or build configuration files to determine the toolchain version. If a file contains multiple version fields, the detector uses a fixed priority order to select the most appropriate one. After identifying a version, the detector sends the version details to the assigner. The assigner checks the Endor Labs toolchain support matrix to verify if the version is supported for the host operating system and architecture. If it doesn’t find an exact match, it selects the closest supported version based on the major version number. This version will be the toolchain used for your project scan. For example, when analyzing Java projects, the Java detector checks config files like `pom.xml` or `build.gradle` to find the Java version used in the project. ### Config files scanned for version detection The following table lists the config files Endor Labs scans to detect the language and version used in your project. The following examples illustrate how to define versions in each config file. Config file: `pom.xml` Define the Java version using any one of the following options: * Using version fields ```bash theme={null} 1.8 1.8 11 17 ``` * Using plugin configuration ```bash theme={null} maven-compiler-plugin 3.8.1 11 11 ``` Config file: `build.gradle` Define the Java version using `sourceCompatibility` and `targetCompatibility`. ```bash theme={null} sourceCompatibility='17' targetCompatibility='17' ``` Ensure the Gradle wrapper version is defined in `gradle/wrapper/gradle-wrapper.properties`. ```bash theme={null} distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-all.zip ``` Specify the Python version in any of the following config files. Use `python_requires` inside the `setup()` block. ```bash theme={null} setup( ... python_requires='>=3.8, <4' ) ``` Use `requires-python` to define the Python version range. ```toml theme={null} [project] requires-python = ">=3.8, <4.0" [tool.poetry.dependencies] python = "3.12.1" ``` Specify the exact Python version. ```bash theme={null} 3.12.1 ``` Specify the NodeJS version in any of the following config files. Use `engines.node` ```json theme={null} "engines": { "node": ">=16.0.0 <19" } ``` Specify the exact NodeJS version. ```bash theme={null} 18.17.1 ``` Specify the exact NodeJS version. ```bash theme={null} 18.17.1 ``` Specify the Yarn version in any of the following config files. Use `engines.yarn` ```json theme={null} "engines": { "yarn": ">=1.22.0 <2.0.0" } ``` Use `yarnPath` ```bash theme={null} yarnPath: ".yarn/releases/yarn-3.2.1.cjs" ``` Use `yarnPath` ```bash theme={null} yarnPath: ".yarn/releases/yarn-3.2.1.cjs" ``` Config file: `package.json` Specify the pnpm version using `engines.pnpm` ```json theme={null} "engines": { "pnpm": ">=6.0.0" } ``` Specify the .NET version using any of the following config files. Use `sdk.version` ```json theme={null} { "sdk": { "version": "7.0.203" } } ``` Use `TargetFramework` or `TargetFrameworks` ```bash theme={null} net6.0 ``` Use `TargetFramework` or `TargetFrameworks` in a `PropertyGroup` to define the .NET version for the directory and subdirectories. ```xml theme={null} net6.0 ``` Use `TargetFramework` or `TargetFrameworks` in a `PropertyGroup` to define the .NET version when using central package management. ```xml theme={null} net6.0 ``` Config file: `go.mod` Use the `go` directive. ```Go theme={null} module github.com/example/project go 1.21 ``` Auto detection is best-effort and works only if your project’s config files are correctly configured. ### Enable auto detection for endorctl scans To enable auto detection for endorctl scans, run: ```bash theme={null} endorctl scan --install-build-tools --enable-build-tools-version-detection ``` Enabling these options downloads the necessary build toolchains during each scan. This works well for one-time scans but may cause scan failures in CI environments due to intermittent network issues. ### Enable auto detection in GitHub App When using the GitHub App, you can enable auto detection either by a project or enable it for all projects in a tenant. * To enable the auto detection by a project, update the project's `meta.annotations` with `"ENDOR_SCAN_ENABLE_BUILD_TOOLS_VERSION_DETECTION":"true"`. ```bash theme={null} meta: annotations: {"ENDOR_SCAN_ENABLE_BUILD_TOOLS_VERSION_DETECTION":"true"} ``` ```bash theme={null} endorctl api update -r Project --uuid= -i ``` * To enable auto detection across all projects in a tenant, update the system config's `meta.annotations` with `"ENDOR_SCAN_ENABLE_BUILD_TOOLS_VERSION_DETECTION":"true"`. ```bash theme={null} meta: annotations: {"ENDOR_SCAN_ENABLE_BUILD_TOOLS_VERSION_DETECTION":"true"} ``` ```bash theme={null} endorctl api update -r SystemConfig --uuid= -i ``` The updates are applied during the next scheduled scan or whenever you perform a manual re-scan. # Configure build tools Source: https://docs.endorlabs.com/scan/scan-profiles/build-tools/index Learn about build tools to build repeatable patterns in your scan environment. Endor Labs uses build tools to scan projects, generate reliable Software Bill of Materials (SBOM), and detect security or operational risks. For languages like Java, Python, and .NET that depend on the build environment, it relies on specific runtime or package manager versions to ensure precise results. When tools are missing, you can define and install them in the CLI, and Endor Labs sets them up in an isolated sandbox during the scan. This feature is supported on Linux and macOS. You need to [install and initialize](/developers-api/cli/install-and-configure) endorctl before configuring the build toolchains in a scan profile. ## Toolchain priority in GitHub App scans [Endor Labs GitHub App](/setup-deployment/scm-integrations/github-app) continuously monitors your projects for security and operational risks. The app monitors all the projects included in your GitHub workspace and scans run once every 24 hours. For performing scans, the GitHub App checks the toolchain specifications in the following order: 1. Scan workflow, if present. 2. Toolchain configuration specified through endorctl API. 3. Toolchain configuration specified in `scanprofile.yaml` file. 4. Enable auto detection to automatically detect the toolchains from your manifest files. 5. Uses the system defaults. ## Configure build tools for endorctl scans After [installing and initializing](/developers-api/cli/install-and-configure) endorctl, run the endorctl scan with the `--install-build-tools` flag to automatically download and install any missing toolchains in an isolated sandbox to properly execute language-specific scans and dependency resolution. 1. For the first time, run the endorctl scan to create a project with Endor Labs. ```bash theme={null} endorctl scan ``` 2. Run the following command to automatically download and install build tools as part of your scan. ```bash theme={null} endorctl scan --install-build-tools ``` 3. The system checks for the required toolchain specifications in the following order before installing them in the sandbox. * [Configure scan workflow through endorctl API](/scan/scan-profiles/configure-scan-workflow-through-api) * [Configure toolchain profile through endorctl API](/scan/scan-profiles/configure-scanprofile-api) * [Configure toolchain profile in the profile.yaml file](/scan/scan-profiles/configure-scanprofile-yaml) * [Automatically detect toolchain profiles](/scan/scan-profiles/auto-detect-toolchains) * [Uses the system defaults](#system-default-toolchain-versions) ## Scan with a preconfigured build environment If your build tools are already installed in your scan environment, use `--use-scan-profile` to apply the project's scan profile configuration without downloading and installing tools in a new sandbox. Endor Labs fetches the scan profile associated with the project and applies its automated scan parameters, including custom paths, environment variables, and any custom scripts, using the tools already available on the machine. This approach is useful when you have a container or CI runner with the required tools already installed and you want the scan profile to control scan behavior. Before you run the scan: 1. Verify that the project already exists in Endor Labs. If it does not, run `endorctl scan` first to create it. 2. Configure a scan profile for the project. See [Configure scan profile through the Endor Labs user interface](/scan/scan-profiles/configure-scanprofile-ui), [through the API](/scan/scan-profiles/configure-scanprofile-api), or [through a YAML file](/scan/scan-profiles/configure-scanprofile-yaml). 3. Verify that the required build tools are installed on the machine. To scan using the project's scan profile, run: ```bash theme={null} endorctl scan --use-scan-profile ``` `--use-scan-profile` and `--install-build-tools` cannot be used at the same time. Use `--install-build-tools` if you want to download and install build tools rather than using pre-installed ones. ## System default toolchain versions If you do not provide a tool profile, the default toolchains are installed in the sandbox while performing the endorctl scan with the `install-build-tools` flag. See [Toolchain support matrix](#toolchain-support-matrix) for details on default versions. ### Toolchain support matrix The following table outlines the toolchain profile support details across different languages and platforms. .NET 5 and earlier versions are not supported for auto detection or manual configuration. If a project uses Java 8, Endor Labs installs both Java 8 and Java 17.0.11. It builds the project with Java 8 and scans it with Java 17. ## Configure automated scan parameters Automated scan parameters are endorctl parameters and environment variables that you define in a scan profile. They apply to projects linked to that profile and help customize scan behavior during cloud scans. You can define the following parameters in your scan profile: * **included\_paths**: Enable to specify a list of paths to include in the scan. * **excluded\_paths**: Enable to specify a list of paths to exclude from the scan. Excluded paths do not apply to secrets scanning. Secrets detection always scans the full repository. To filter or suppress secret findings, use policies or a `.gitleaksignore` file instead. * **languages**: Enable to specify a list of languages to scan. If empty, default values are used. * **call\_graph\_languages**: Enable to specify a list of languages to use for generating call graphs. If empty, default values are used. * **segment\_match\_languages**: Enable to specify a list of languages to scan using segment-based analysis. * **additional\_environment\_variables**: Enable to specify additional environment variables to set during the scan. Only the environment variables starting with `ENDOR_` are passed to the scan, all others are ignored. See [Global flags and environment variables](/developers-api/cli/environment-variables) for a complete list of available environment variables. * **enable\_automated\_pr\_scans**: Enables automatic scanning of pull request changes. * **enable\_pr\_comments**: Enables adding scan results as comments in pull requests. * **enable\_sast\_scan**: Enables SAST during the scanning process. * **disable\_code\_snippet\_storage**: Disables the storage of code snippets. If you are using Bazel in your build, you can further configure: * **bazel\_configuration**: Enable to specify configuration settings for Bazel scans. See [Bazel flags](/developers-api/cli/commands/scan#bazel-flags) for more details. * **bazel\_show\_internal\_targets**: Enable to include internal build targets in the dependency analysis. * **bazel\_workspace\_path**: Enable to specify the path to the Bazel workspace. * **bazel\_include\_targets**: Enable to specify Bazel targets to include in the scan. * **bazel\_exclude\_target**: Enable to specify Bazel targets to exclude from the scan. The following toolchain profile shows a yaml definition with configured automated scan parameters: ```yaml expandable theme={null} kind: AutomatedScanParameters spec: automated_scan_parameters: included_paths: - python/** excluded_paths: - java/** languages: - python call_graph_languages: - python additional_environment_variables: - ENDOR_LOG_VERBOSE=true - ENDOR_LOG_LEVEL=debug enable_automated_pr_scans: true enable_pr_comments: true enable_sast_scan: true disable_code_snippet_storage: true bazel_configuration: bazel_show_internal_targets: true bazel_workspace_path: "go-bazel-repo/" bazel_include_targets: bazel_abs: - "//cmd:cmd" ``` # Configure scan workflow through Endor Labs API Source: https://docs.endorlabs.com/scan/scan-profiles/configure-scan-workflow-through-api/index Learn how to configure scan workflow through Endor Labs API Configure scan workflows through the Endor Labs API to automate how your projects are scanned. You can create, modify, and delete scan workflows. You can also define the order of scan profile execution and associate workflows with specific projects in your tenant. ### Prerequisites for creating a scan workflow Ensure you have the following before creating a scan workflow: * Make sure you [install and configure endorctl](/developers-api/cli/install-and-configure) in your system. * Ensure your scan workflow includes at least one [scan profile](/scan/scan-profiles). * All scan profiles you reference must already exist in your tenant. * You can associate only one scan workflow with each project. ### Create a scan workflow Create a scan workflow using `endorctl api` and associate it with a project in your tenant. 1. Run the endorctl scan to create a project in Endor Labs. ```bash theme={null} endorctl scan ``` 2. Fetch the UUID of the project. For example, to fetch the UUID of `app-java-demo` project, run: ```bash theme={null} UUID=$(endorctl api list -r Project --filter="meta.name matches https://github.com/endorlabs/app-java-demo" --field-mask=uuid | jq -r '.list.objects[].uuid') ``` 3. Use the following command to create a `ScanWorkflow` object and associate it with your project. Specify the title and UUID of one or more scan profiles available in your tenant. Replace the following placeholders with your actual values: * `demo` with name the of the scan workflow. * `project-uuid` with the UUID of your project from step 2. * `scan profile 1` and `scan profile 2` with the names of your scan profiles. * `uuid of scan profile 1` and `uuid of scan profile 2` with the corresponding UUIDs of the scan profiles. ```bash theme={null} endorctl api create -r ScanWorkflow -d'{ "meta": { "name":"demo", "kind": "ScanWorkflow", "parent_kind":"Project", "parent_uuid":"project-uuid" }, "spec": { "steps": [ { "title":"scan profile 1", "scan_profile_uuid":"uuid of scan profile 1" }, { "title":"scan profile 2", "scan_profile_uuid":"uuid of scan profile 2" }, ] } }' ``` Here is an example to create a scan workflow titled `demo-workflow` with a `Java` scan profile and `Python` scan profile. ```bash expandable theme={null} endorctl api create -r ScanWorkflow -d'{ "meta": { "name":"demo-workflow", "kind": "ScanWorkflow", "parent_kind":"Project", "parent_uuid":"68369123e4a717bd735c24bc" }, "spec": { "steps": [ { "title":"java", "scan_profile_uuid":"68450261ec0014616fa6c0c3" }, { "title":"python", "scan_profile_uuid":"6845023bbe385224df4a0526" } ] } }' ``` ### View provision result of a scan workflow The provision result shows the list and execution history of scan workflows in your namespace, including the scan profiles used, their order, and the outcome of each step. It verifies that prerequisites such as resources, configurations, and dependencies are ready before scanning or analytics begin. You can use it to troubleshoot failures, check that the correct scan profiles ran, and confirm workflows run as expected. Run the following command to view the list of scan workflows in your namespace and their execution results. ```bash theme={null} endorctl api list -r ScanWorkflowResult ``` ### Delete a scan workflow You can delete an existing scan workflow from your tenant by using `endorctl` API and specifying its UUID. 1. Get a list of scan workflows in your namespace. ```bash theme={null} endorctl api list -r ScanWorkflow ``` 2. Run the following command to delete a scan workflow. Replace `abcde12345` with the UUID of the scan workflow. ```bash theme={null} endorctl api delete -r ScanWorkflow --uuid abcde12345 ``` # Configure scan profile through Endor Labs API Source: https://docs.endorlabs.com/scan/scan-profiles/configure-scanprofile-api/index Learn how to configure scan profile through Endor Labs API You can use the `endorctl api` command to configure the toolchains for your project. 1. Run the endorctl scan to create a project in Endor Labs. ```bash theme={null} endorctl scan ``` 2. Fetch the UUID of the project. For example, to fetch the UUID of `app-java-demo` project, you can use: ```bash theme={null} UUID=$(endorctl api list -r Project --filter="meta.name matches https://github.com/endorlabs/app-java-demo" --field-mask=uuid | jq -r '.list.objects[].uuid') ``` 3. Create a `ScanProfile` object using the following command. Set the environment variable using `set EDITOR=vim` before executing the following command. ```bash theme={null} endorctl api create -i -r ScanProfile ``` You can configure automated scan parameters in your scan profile. See [automated scan parameters](/scan/scan-profiles/build-tools#configure-automated-scan-parameters) to learn more. **Segment-based analysis** To scan using segment-based analysis for C/C++ and C# projects, set `segment_match_languages` under `spec.automated_scan_parameters`. See [Scan C/C++ projects with segment-based analysis](/scan/sca/c#scan-cc-projects-with-segment-based-analysis) or [Scan C# projects with segment-based analysis](/scan/sca/dotnet#scan-c-projects-with-segment-based-analysis) for examples. Here is an example that you can use to create a `ScanProfile` object for installing `Java 8` and `Maven 3.9.4` in Linux and macOS. After executing this command, you can fetch the UUID of the `ScanProfile` object. See [toolchain support matrix](/scan/scan-profiles/build-tools#toolchain-support-matrix) for a complete description of supported toolchains. ```yaml expandable theme={null} meta: name: "demo" spec: automated_scan_parameters: languages: - java additional_environment_variables: - ENDOR_LOG_VERBOSE=true - ENDOR_LOG_LEVEL=debug enable_automated_pr_scans: true enable_pr_comments: true enable_sast_scan: true disable_code_snippet_storage: true bazel_configuration: bazel_show_internal_targets: true bazel_workspace_path: "go-bazel-repo/" bazel_include_targets: - "//cmd:cmd" toolchain_profile: os: linux: arch: amd64: java_tool_chain: version: name: "1.8.412" urls: - "https://builds.openlogic.com/downloadJDK/openlogic-openjdk/8u412-b08/openlogic-openjdk-8u412-b08-linux-x64.tar.gz" relative_tool_chain_path: "openlogic-openjdk-8u412-b08-linux-x64/" sha256_sum: "eb06c9d62e031e3290f499a828cae66d4fadbf62eb8f490c63c8406b1a80172e" maven_version: name: "3.9.4" urls: - "https://repo1.maven.org/maven2/org/apache/maven/apache-maven/3.9.4/apache-maven-3.9.4-bin.tar.gz" relative_tool_chain_path: "apache-maven-3.9.4" sha256_sum: "ff66b70c830a38d331d44f6c25a37b582471def9a161c93902bac7bea3098319" darwin: arch: arm64: java_tool_chain: version: name: "1.8.412" urls: - "https://builds.openlogic.com/downloadJDK/openlogic-openjdk/8u412-b08/openlogic-openjdk-8u412-b08-mac-x64.zip" relative_tool_chain_path: "openlogic-openjdk-8u412-b08-mac-x64/jdk1.8.0_412.jdk/Contents/Home" sha256_sum: "a16d297418f6800dfc5abfd4dfd8a16c0504d7e1f3b6fc9051cf2460f14a955e" maven_version: name: "3.9.4" urls: - "https://repo1.maven.org/maven2/org/apache/maven/apache-maven/3.9.4/apache-maven-3.9.4-bin.tar.gz" relative_tool_chain_path: "apache-maven-3.9.4" sha256_sum: "ff66b70c830a38d331d44f6c25a37b582471def9a161c93902bac7bea3098319" ``` 4. Associate the `scan_profile_uuid` to your project UUID `project-uuid` using the following command. ```bash theme={null} endorctl api update -r Project --uuid= -d '{"spec":{"scan_profile_uuid":""}}' --field-mask 'spec.scan_profile_uuid' ``` # Configure scan profile through Endor Labs user interface Source: https://docs.endorlabs.com/scan/scan-profiles/configure-scanprofile-ui/index Learn how to configure scan profile through the Endor Labs user interface. While scanning projects using the GitHub App, you can configure a scan profile and assign it to your projects directly from the Endor Labs user interface. ## Create a new scan profile Create and customize a new scan profile to define scan parameters, toolchains, and projects. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Scan Profiles** and click **New Scan Profile**. 3. Enter a name for the scan profile and click **Create Scan Profile**. 4. Configure settings such as automated scan parameters and paths. See [Configure general scan profile settings](#configure-general-scan-profile-settings) for more information. 5. Select **Toolchains** and configure the toolchains. See [Configure toolchains](#configure-toolchains) for more information. 6. Select **Projects** to associate the scan profile with projects. See [Associate projects with a scan profile](#associate-projects-with-a-scan-profile). ### Configure general scan profile settings Configure the necessary scan settings to tailor scans for your projects. 1. Under **Developer Workflows**, choose how Endor Labs integrates with your source provider for pull requests and SAST. * **Pull Request Scans**: Automatically scans changes in the pull request. * **Pull Request Comments**: Adds scan results as comments on the pull request. * **AI Security Review Scans**: Runs AI security review scans. * **Disable Code Snippet Storage for SAST**: Disable storing the code snippet. * **Enable the False Positive reduction agent**: Enable the [AI SAST triage agent](/scan/ai-sast/triage-agent) to automatically classify rule-based SAST findings as true positives or false positives. This feature requires an Endor Code Pro license. See [automated scan parameters](/scan/scan-profiles/build-tools#configure-automated-scan-parameters) to learn more. 2. Select the languages to scan. * **Languages**: Select the languages to scan. If you don't select any language, all the languages detected in the repository will automatically be selected for the scan. * **Call Graph Languages**: Select the languages for which you need to generate call graphs. * **Segment Match Languages**: Select the languages to scan using segment-based analysis. Adding a language to **Segment Match Languages** scans it with segment-based analysis and does not affect any other selected languages. You can select any combination of languages across all three fields. 3. Enter the paths to include or exclude in the scan. 4. Enter any additional environment variables, if required. Only the environment variables starting with `ENDOR_` are passed to the scan, all others are ignored. See [Global flags and environment variables](/developers-api/cli/environment-variables#environment-variables) for available environment variables. 5. Select an exporter to define what scan results to send, in which format, and to which external system. For example, you can select the SARIF exporter to export the scan results in the SARIF format. See [Export findings to GitHub Advanced Security](/integrations/data-exporters/export-to-ghas) for more information. 6. Configure Bazel settings, if required. * Select **Show Internal Targets as Dependencies** to include internal build targets in your dependency analysis while using Bazel as your build system. * Configure the following Bazel settings: * **Bazel Workspace Path**: Specify the location of the Bazel workspace. * **Target Selection**: Choose one of the following methods to define which targets should be scanned: * **Include Targets**: Specify individual Bazel targets to be scanned. * **Targets Query**: Use a Bazel query expression to define the targets dynamically. * **Excluded Targets**: If using **Include Targets**, do not set **Excluded Targets**, as they cannot be used together. See [Scan using Bazel](/scan/bazel) for more details on Bazel scanning and target queries. 7. Click **Save Scan Profile** to save your changes. ### Configure toolchains Create and save a scan profile. 1. Select the operating system for the scan profile. 2. Select the architecture. 3. Select the toolchain available for the operating system-architecture combination. 4. Select the tool associated with the toolchain. For package managers like Python (pip), JavaScript (npm), and Android, you can configure a list of packages to install before the scan. 5. Select the version of the tool (or enter the package name if you chose a package in the previous step) and click **Add to Profile**. You can only assign one version of the tool for a scan profile for a particular operating system-architecture combination. You can also click **Custom** and define the custom version of the tool. See [Configure custom versions](#configure-a-custom-version-for-a-tool) for more information. The following image shows the creation of a scan profile for Go and JavaScript scans. Create Scan Profile 6. Click **Save Scan Profile** to save the toolchain configuration. #### Configure a custom version for a tool When you assign a version of the tool, you can choose to apply a custom version that is not provided by Endor Labs. You must provide the following information. * Version name * The URL to download the archive package * SHA256 checksum of the package * The relative toolchain path, if required. The toolchain is extracted to the specified relative toolchain path if provided. The following image shows a custom configuration for the Golang toolchain with Go 1.22.7 instead of the bundled 1.22.6. Custom toolchain ### Associate projects with a scan profile Assign projects to your scan profile. 1. Select **Projects**. 2. Select **Actions** > **Add Projects**. Scan profile Projects tab with Actions and Add Projects 3. Search the project and click **Add to Scan Profile**. You can associate multiple projects with a scan profile, but you cannot apply multiple scan profiles to a single project. ## Manage scan profiles You can edit, clone, delete, or set a default scan profile for a namespace. ### Set a default scan profile You can set a default scan profile for a namespace, and all projects within that namespace will use this profile. Child namespaces inherit the default scan profile unless you override it by setting a different profile as the default within the child namespace. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Scan Profiles** to view the list of scan profiles. 3. Choose a scan profile, click the vertical ellipsis on the right side, and select **Set As Default**. ### Edit scan profile You can modify the configuration of a scan profile after creating it. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Scan Profiles**. 3. Click on the vertical three dots of the scan profile you want to edit. 4. Select **Edit**. 5. Modify the scan profile details such as description, GitHub app features, languages, toolchains, projects it is associated with, etc. 6. Click **Save Scan Profile**. ### Clone scan profile You can clone a scan profile so that existing configurations of the scan profile are duplicated with all parameters intact, ensuring faster setup and consistent scan settings. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Scan Profiles**. 3. Click on the vertical three dots of the scan profile you want to clone. 4. Select **Clone**. ### Delete scan profile You can delete a scan profile from your namespace, which automatically removes it from any associated projects as well. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Scan Profiles**. 3. Click on the vertical three dots of the scan profile you want to delete. 4. Select **Delete**. 5. Click **Delete** to confirm the deletion of the scan profile from the namespace. Delete scan profile ## Configure build tools Instead of [configuring a custom version for a tool](#configure-a-custom-version-for-a-tool) every time a required version is not provided by Endor Labs, you can create a standard version and use it across all scan profiles. For example, you can add dotnet 5.0—which is not a standard supported version—to your build tools and make it available. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Build Tools**. 3. Click **New Build Tool**. 4. Select the **OS** and **Architecture**. 5. Enter the required version, the download URL, and the SHA 256 checksum for verification. In advanced options, you can optionally specify a relative toolchain path. For example, you can enter these values to configure .NET 5.0 build chain: * **OS** - Linux * **ARCHITECTURE** - arm64 * **TOOLCHAINS** - .NET * **NAME** - 5.0.408 * **URL** - [https://builds.dotnet.microsoft.com/dotnet/Sdk/5.0.408/dotnet-sdk-5.0.408-linux-arm64.tar.gz](https://builds.dotnet.microsoft.com/dotnet/Sdk/5.0.408/dotnet-sdk-5.0.408-linux-arm64.tar.gz) * **SHA256** - da88dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 6. Use the **Relative Toolchain Path** to specify a custom installation directory for the tool. 7. Click **Add Build Tool**. You will be able to choose this build tool in **TOOLCHAINS**, while creating a [scan profile](#create-a-new-scan-profile). # Configure scan profile through scanprofile.yaml Source: https://docs.endorlabs.com/scan/scan-profiles/configure-scanprofile-yaml/index Learn how to configure scan profile through scanprofile.yaml file You can create a build tool profile for your Endor Labs scans in each repository to specify the build tools to automatically download for each scan. Create a new file `.endorctl/scanprofile.yaml` file in the root directory of your repository and specify the required versions of the tools. You can specify the Operating system, architecture, automated scan parameters, language, tool, and install information in the scanprofile.yaml file: The following snippet shows the overall structure of a `scanprofile.yaml` file with automated scan parameters. See [automated scan parameters](/scan/scan-profiles/build-tools#configure-automated-scan-parameters) to learn more. **Segment-based analysis** To scan using segment-based analysis for C/C++ and C# projects, set `segment_match_languages` under `spec`. See [Scan C/C++ projects with segment-based analysis](/scan/sca/c#scan-cc-projects-with-segment-based-analysis) or [Scan C# projects with segment-based analysis](/scan/sca/dotnet#scan-c-projects-with-segment-based-analysis) for examples. ```yaml expandable theme={null} kind: "AutomatedScanParameters" spec: languages: - java call_graph_languages: - java additional_environment_variables: - ENDOR_LOG_VERBOSE=true - ENDOR_LOG_LEVEL=debug enable_automated_pr_scans: true enable_pr_comments: true enable_sast_scan: true disable_code_snippet_storage: true bazel_configuration: bazel_show_internal_targets: true bazel_workspace_path: "go-bazel-repo/" bazel_include_targets: - "//cmd:cmd" ``` The following example shows a scan profile to scan `Java` and Bazel projects in CI with `Maven 3.9.4`, custom environment variables, and support for both Linux and macOS toolchains. ```yaml expandable theme={null} kind: "AutomatedScanParameters" spec: languages: - java additional_environment_variables: - ENDOR_LOG_VERBOSE=true - ENDOR_LOG_LEVEL=debug enable_automated_pr_scans: true enable_pr_comments: true enable_sast_scan: true disable_code_snippet_storage: true bazel_configuration: bazel_show_internal_targets: true bazel_workspace_path: "go-bazel-repo/" bazel_include_targets: - "//cmd:cmd" --- kind: "ToolchainProfile" spec: os: linux: arch: amd64: java_tool_chain: version: name: "1.8.412" urls: - "https://builds.openlogic.com/downloadJDK/openlogic-openjdk/8u412-b08/openlogic-openjdk-8u412-b08-linux-x64.tar.gz" relative_tool_chain_path: "openlogic-openjdk-8u412-b08-linux-x64/" sha256_sum: "eb06c9d62e031e3290f499a828cae66d4fadbf62eb8f490c63c8406b1a80172e" maven_version: name: "3.9.4" urls: - "https://repo1.maven.org/maven2/org/apache/maven/apache-maven/3.9.4/apache-maven-3.9.4-bin.tar.gz" relative_tool_chain_path: "apache-maven-3.9.4" sha256_sum: "ff66b70c830a38d331d44f6c25a37b582471def9a161c93902bac7bea3098319" darwin: arch: arm64: java_tool_chain: version: name: "1.8.412" urls: - "https://builds.openlogic.com/downloadJDK/openlogic-openjdk/8u412-b08/openlogic-openjdk-8u412-b08-mac-x64.zip" relative_tool_chain_path: "openlogic-openjdk-8u412-b08-mac-x64/jdk1.8.0_412.jdk/Contents/Home" sha256_sum: "a16d297418f6800dfc5abfd4dfd8a16c0504d7e1f3b6fc9051cf2460f14a955e" maven_version: name: "3.9.4" urls: - "https://repo1.maven.org/maven2/org/apache/maven/apache-maven/3.9.4/apache-maven-3.9.4-bin.tar.gz" relative_tool_chain_path: "apache-maven-3.9.4" sha256_sum: "ff66b70c830a38d331d44f6c25a37b582471def9a161c93902bac7bea3098319" ``` # Configure scan workflow through Endor Labs user interface Source: https://docs.endorlabs.com/scan/scan-profiles/configure-scanworkflow-through-ui/index Learn how to configure scan workflow through the Endor Labs user interface. Configure scan workflows to define how your projects are scanned. You can assign [scan profiles](/scan/scan-profiles) to scanning steps and control their order of execution, and manage these settings in the Endor Labs user interface. ## Set up a scan workflow Set up a scan workflow to define scanning steps, assign profiles, and manage how your projects are scanned. 1. Select **Projects** from the left sidebar. 2. Select the project for which you want to configure a scan workflow. 3. Navigate to **Settings** and select **Scan Workflow**. 4. Click **Add Step** to add an existing scan profile. 5. Enter a descriptive name in **Step title** to describe the workflow step. 6. Select a scan profile from your namespace for this step. 7. Click **Save** to add this step, and repeat to add as many steps as you need. 8. Toggle **Enabled** for each step to choose which steps to include in the workflow during the scan. 9. Configure additional options in GitHub App features. See [GitHub App features](#set-up-github-app-features) for more information. 10. Click **Save**. ### Set up GitHub App features Configure GitHub App features in scan workflows to enable pull request scanning, AI security reviews, and custom scan settings for your projects. 1. Select the pull request flags you want to enable for the scan workflow. * **Pull request scans**: Automatically scan changes in the pull request. * **Pull request comments**: Add scan results as comments in the pull request. 2. Select the AI Security Review settings that you want to enable for the scan workflow. * **AI Security Review Scans**: Automatically analyze code repositories with AI, detect vulnerabilities and misconfigurations, and generate detailed security reports. * **Disable Code Summary**: Exclude the code summary from the AI Security Review scan report. * Enter a **Custom Prompt** to modify how AI Code Security Review detects and categorizes security related changes. You can use this only when **AI Security Review Scans** is enabled. 3. Select **Disable code snippet storage for SAST** to exclude code summary from the AI Security Review scan report. See [automated scan parameters](/scan/scan-profiles/build-tools#configure-automated-scan-parameters) to learn more. 4. Enter any additional environment variables, if required. Only the environment variables starting with `ENDOR_` are passed to the scan, all others are ignored. 5. Click **Save**. GitHub App feature settings defined in the scan workflow take precedence over those specified in the individual scan profiles. ## Customize scan workflow Customize the scan workflow to control which profiles, checks, and features are applied to your project. ### Edit scan workflow To edit the steps in your scan workflow: 1. Select the project for which you want to configure a scan workflow. 2. Navigate to **Settings** and select **Scan Workflow**. 3. Click **Edit Step** and update the step title. 4. Select a different scan profile to replace the one associated with the step. 5. Click **Save**. ### Remove a step from scan workflow To remove a step from the scan workflow: 1. Select the project for which you want to configure a scan workflow. 2. Navigate to **Settings** and select **Scan Workflow**. 3. Click **Remove**. # Scan Profiles Source: https://docs.endorlabs.com/scan/scan-profiles/index Configure scan profiles to customize how your projects are scanned. A scan profile is a configuration that defines the scan parameters, and toolchains for each build setup required for a scan. Use scan profiles to ensure accurate scans and reduce failures caused by missing or mismatched dependencies. Associate a project with an appropriate scan profile to ensure that each scan uses the correct configuration. You can also [configure automated scan parameters](/scan/scan-profiles/build-tools#configure-automated-scan-parameters) in your scan profile to customize scan behavior in cloud environments. Build tools in a scan profile help recreate the project’s build environment, ensuring reliable dependency resolution and accurate scans. See [build tools](/scan/scan-profiles/build-tools) to configure them and view the toolchains supported by Endor Labs. Use one of the following methods to create a scan profile: * [Configure scan profile through the Endor Labs user interface](/scan/scan-profiles/configure-scanprofile-ui) * [Configure scan profile through the Endor Labs API](/scan/scan-profiles/configure-scanprofile-api) * [Configure scan profile through `scanprofile.yaml` file](/scan/scan-profiles/configure-scanprofile-yaml) ## Scan workflow A scan workflow is a predefined sequence of scan steps that runs within a project. Each step applies a specific scan profile, enabling you to target different parts of your codebase. Analytics are generated once the entire workflow completes. A project can have only one scan workflow at a time. Use scan workflows to combine multiple scan profiles and apply them selectively—for example, when your project uses different languages or build tools across multiple components. Use the following method to create a scan workflow: * [Configure scan workflow through the Endor Labs API](/scan/scan-profiles/configure-scan-workflow-through-api) * [Configure scan workflow through the Endor Labs user interface](/scan/scan-profiles/configure-scanworkflow-through-ui) You require **Admin** role permissions to create and manage scan profiles and scan workflows. See [authorization roles](/platform-administration/rbac/authorization-roles) to learn about the different roles Endor Labs offers. # Secrets detection Source: https://docs.endorlabs.com/scan/secrets/index Detect leaked credentials and sensitive data in your codebase. Secrets are access credentials such as passwords, API keys, and personal access tokens that grant access to services and resources. When a secret is committed to a repository, anyone with access to the code, now or later, can use it to reach the services it unlocks. Leaked secrets lead to data breaches, unauthorized access, financial loss, and compliance violations. Endor Labs scans your source code and Git history for leaked secrets so your teams can find and revoke exposed credentials before they are abused. ## How secret detection works Endor Labs detects secrets in stages so that scans stay fast and findings stay actionable: * **Keyword pre-filter**: A fast string check narrows the files that a rule evaluates. * **Pattern match**: A regular expression identifies candidate secrets. * **Entropy check**: An optional Shannon entropy threshold filters out low-randomness matches, such as common words. * **Validation**: For supported credential types, Endor Labs sends a request to the issuing service to determine whether the secret is still active. Active secrets are raised as critical findings so that you can prioritize them. ## Capabilities Use built-in system rules or create custom rules to detect secrets for any service. Scan source code, Git history, changed files, or staged commits with endorctl. Review, prioritize, and remediate the secrets that Endor Labs detects. ## Supported secrets Endor Labs detects secrets using a large set of built-in system rules that cover common providers and credential formats, including: * Cloud provider credentials, such as AWS, Google Cloud, and Azure. * Source control and CI tokens, such as GitHub, GitLab, and Bitbucket. * API keys for services, such as Slack, Twilio, Datadog, Stripe, and OpenAI. * OAuth tokens and personal access tokens. * Private keys and certificates. Endor Labs maintains the system rules and updates them over time. To see the exact rules available in your environment, list them with endorctl. ```bash theme={null} endorctl api list -r SecretRule -n --list-all ``` To detect a credential format that no system rule covers, create a custom rule. See [Manage secret rules](/scan/secrets/secret-rules). ## Scan modes The scan mode determines where rules come from and whether the scan needs to reach Endor Labs. For the commands behind each mode, see [Scan for secrets](/scan/secrets/scan-secrets). ## Incremental secret scans Endor Labs scans incrementally so that repeated scans stay fast as your Git history and pull requests grow. Incremental behavior applies in two places. * **Git history**: After the first [`--git-logs`](/scan/secrets/scan-secrets#scan-complete-history) scan examines the full reachable history, later scans examine only the commits added since the last scan. Endor Labs falls back to a full rescan the first time a repository's history is scanned, and whenever a secret rule in the namespace changes. Run a scan with `--force-rescan` to re-examine the entire history on demand. * **Pull requests**: Pass `--pr-incremental`, or enable pull request scans in a [monitoring scan](/setup-deployment/scm-integrations), to scan only the files that changed relative to the baseline branch instead of the whole repository. See [Perform incremental PR scan](/scan/pr-scans#perform-incremental-pr-scan). To limit a single scan to changed files without comparing against a baseline, use [`--diff-scope`](/scan/secrets/scan-secrets#scan-changed-files-only). ## Secrets deduplication Duplicate secrets increase the attack surface and the risk of unauthorized access. Managing multiple duplicate secrets can be complex and error-prone. Endor Labs categorizes instances of identical secrets found within your application components and repositories, helping an organization achieve: * **Efficient prioritization**: Simplifies the prioritization of widely dispersed secrets, because more occurrences signify increased exposure and risk. * **Comprehensive visibility**: Ensures you have a complete view of all instances associated with a specific secret, which helps when the secret is discovered or changes. * **Optimized issue handling**: Generates a single finding for multiple instances of a secret, simplifying the work of managing and addressing related findings together. # Scan for secrets Source: https://docs.endorlabs.com/scan/secrets/scan-secrets/index Scan for secrets in your source code Run `endorctl scan --secrets` to scan for leaked secrets in your source code. You can also scan for secrets with [monitoring scans](/setup-deployment/scm-integrations) and [CI scans](/setup-deployment/ci-cd). Ensure that you select **Secrets** as a scan type when you install the Endor Labs App for your SCM to scan for secrets during monitoring scans. The following table lists the options available with endorctl for secrets scan. ## Scan methods You can perform the following types of scans to detect secrets: * [**Scan a specific code reference**](#scan-a-specific-code-reference): Scan for secrets only on a defined path in the context of a checked-out branch, commit SHA or tag to identify secrets and raise findings. This helps you to identify secrets that are leaked in the context of what you are working on right now. * [**Scan complete history**](#scan-complete-history): Scan for secrets in all existing branches or tags to identify if a secret has ever been leaked in the history of the project and raise findings. This helps you to identify if any secret has ever been leaked even if it was not leaked in the context of what you are working on right now. * [**Scan pre-commits**](#scan-pre-commits): Scan for secrets in the code before committing the code to your repository during the automated pre-commit checks. This helps you identify and remove sensitive information from your code files early in the development life cycle. * [**Scan with custom rules offline**](#scan-with-custom-rules-offline): Include the custom secret rules from your namespace in a `--pre-commit-checks` or `--local` scan by exporting them to a file, without connecting to Endor Labs. * [**Scan changed files only**](#scan-changed-files-only): Limit a secrets scan to the files that changed to speed up pre-commit and pre-merge workflows. ### Scan a specific code reference By default, a secrets scan searches the files in the path where you start the scan. Run the following command in the directory of the code reference to scan for secrets. ```bash theme={null} endorctl scan --secrets ``` `--dependencies` runs a separate dependency scan, not a secrets scan option. To run both in one command, combine the flags: `endorctl scan --secrets --dependencies`. ### Scan complete history You can scan the Git logs by using the complete history scan. The repository should be present in the scanned path. Endor Labs examines the entire repository history to search for secrets. To perform a complete scan, include the `--git-logs` option in the command line. ```bash theme={null} endorctl scan --secrets --git-logs ``` Add `--dependencies` to also run a dependency scan in the same command. ```bash theme={null} endorctl scan --secrets --git-logs --dependencies ``` The `--git-logs` option scans the repository's Git logs using the following logic: * Perform a full scan if it is the first time the repository's Git log history is scanned. * Perform a full rescan if a change has been detected to any of the rules in the namespace. * Perform an incremental scan based on the last time a scan was performed in all the other cases. Run the following command to force a full rescan if any of the detected secrets are no longer valid, and you want to accurately reflect the state of the secrets. ```bash theme={null} endorctl scan --secrets --force-rescan ``` You can combine `--force-rescan` with `--dependencies` in the same way. ```bash theme={null} endorctl scan --secrets --force-rescan --dependencies ``` ### Scan pre-commits You can check for secrets before committing the code to the repository as part of pre-commit hooks. You must [install and initialize endorctl](/developers-api/cli/install-and-configure) before scanning the pre-commits. 1. Create a `.git/hooks/pre-commit` file at the root of your Git repository to configure the pre-commit hook. It runs automatically when you make a commit and looks for secrets in your commit. ```bash theme={null} cd .git/hooks touch pre-commit ``` 2. Edit the `.git/hooks/pre-commit` and include: ```bash theme={null} #!/bin/bash # # Script invoked on git commit. # if ! endorctl scan --pre-commit-checks --secrets; then echo "Pre-commit checks failed" exit 1 fi echo "No secrets found: Pre-commit checks succeeded" ``` `--pre-commit-checks` scans only the changes you are about to commit to the repository. 3. Set the file permissions to make it executable. ```bash theme={null} chmod +x .git/hooks/pre-commit ``` You can't push the `.git/hooks/` folder to the Git repository because it's only recognized locally on your system. To include the pre-commit code in the Git repository, save it in a different location, like a `hooks/` directory, and then copy it into `.git/hooks/`. This way, you can push the hook code to your Git repository. 4. You can set up this hook on other systems in your organization by creating a script and running it on each system. ```bash theme={null} sh setup-hooks.sh #!/bin/sh # Copy all hooks to .git/hooks cp hooks/* .git/hooks/ chmod +x .git/hooks/* ``` Here's an example output when no secrets are found. No secrets Here's an example when secrets are detected and the commit fails. Secrets found ### Scan with custom rules offline By default, `--pre-commit-checks` and `--local` scans use the secret rules built into the `endorctl` binary. They run fully offline but do not include the custom rules in your namespace. To use your namespace rules offline, export them to a file and pass that file to the scan. 1. Export your rules to a YAML file. ```bash theme={null} endorctl api list -r SecretRule -o yaml --list-all > secret-rules.yaml ``` 2. Run the scan with the exported file. ```bash theme={null} endorctl scan --secrets --pre-commit-checks --secret-rules-file secret-rules.yaml ``` The file replaces the built-in rules for that scan. The scan stays offline and needs no API key. Re-export the file after you upgrade `endorctl`, because the scan rejects a file whose schema does not match the running binary. ### Scan changed files only Use `--diff-scope` to limit a secrets scan to files that changed, which speeds up scans in pre-commit and pre-merge workflows. The flag requires endorctl v1.7.1040 or later and accepts two values: * `local`: Scan files with local edits, including staged, unstaged, and untracked changes, against the current `HEAD`. * `baseline`: Scan files that changed against the repository default branch. Endor Labs reports only secrets on lines that the change adds or modifies. Untracked files are new, so all findings in them are reported. Run the following command to scan only the files changed against the default branch. ```bash theme={null} endorctl scan --secrets --diff-scope baseline ``` `--diff-scope` cannot be combined with `--pre-commit-checks`, `--local`, `--git-logs`, or `--force-rescan`, because each of those modes defines its own scan range. ## Exclude false positives from secret scans A scan can flag a value that is safe, such as a test credential or an example token. Endor Labs offers three ways to suppress a false positive, from the narrowest to the broadest. ### Annotate a safe line Add an `endorctl:allow` comment to mark a non-sensitive line, such as a test value. ```bash theme={null} # These are test credentials, safe to commit username = "test_user" # endorctl:allow password = "test_password" # endorctl:allow ``` ### Allowlist a pattern in a rule To exclude a known false positive from every scan of a rule, add an allowlist to the rule. Allowlists match on content, path, commit, or stop words. See [Allowlists](/scan/secrets/secret-rules#allowlists). ### Dismiss a finding To suppress an individual finding after a scan, create a finding exception. Exceptions are managed through finding policies. See [Finding policies](/platform-administration/policies/finding-policies). ## Scan for secrets using regular expression Endor Labs scans for secrets based on regular expressions that are designed to detect the presence of a secret. It then validates the discovered secrets against external APIs to identify if they are valid. Valid secrets actively provide access to a service or an application and can be used to gain unauthorized access. Regular expressions are customized to match specific types of secrets, such as GitHub personal access tokens, OAuth access tokens, AWS access tokens, OpenAI keys, Client IDs, Client Secrets, and more. For example, you can describe a GitHub Personal Access Token with the following regular expression. ```bash theme={null} github_pat_[0-9a-zA-Z_]{82} ``` # Manage secret rules Source: https://docs.endorlabs.com/scan/secrets/secret-rules/index Use secret rules to scan and detect secrets You can use the following rules to scan your codebase and detect secrets: * **System rules**: Endor Labs provides out-of-the-box rules for secret patterns for many public services like GitHub, GitLab, AWS, Bitbucket, Dropbox, and more. * **Custom rules**: If you are using a service that is not included in the out-of-the-box list of secret patterns provided by Endor Labs, you can build your own custom rule to scan and detect the secrets for any service. The following table lists the most important fields of the rule definition. ### Automatic rule identifiers When you create a secret rule from the CLI or API, `spec.rule_id` is optional. If you leave it empty, Endor Labs derives it from the rule name by lowercasing the name and replacing each run of non-alphanumeric characters with a hyphen. For example, a rule named `My Custom Rule` becomes `my-custom-rule`. If the generated identifier already exists in your namespace, Endor Labs appends a short unique suffix, such as `my-custom-rule-3f1a9c2b`. A `rule_id` you supply yourself is always used unchanged. Creating a secret rule in the Endor Labs user interface still requires a **Rule Identifier**. The automatic identifier applies to rules created with endorctl and the API. ## Create a secret rule 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Secret Rules**. 3. Click **Create Secret Rules**. Create secret rules 4. Enter the unique **Rule Identifier** and **Rule Name**. 5. Enter the **Description** of the secret rule. 6. Enter the regex for the secret rule in **Detection Rule**. 7. Optionally, enter keywords for pre-regex filtering as comma-separated values in **Keywords**. Keywords are recommended because a file is matched against the regex only when it contains one of them, which keeps scans fast. 8. Optionally, enter the minimum Shannon entropy a regex group must have to be considered in **Entropy**. This helps filter out low randomness matches, like common words or predictable strings, and ensures only high-entropy values, more likely to be secrets, such as keys or tokens, are flagged. 9. Optionally, add validation details to validate the secret: * **Validation URL**: Enter the URL for validation. * **HTTP Method**: Choose `GET` or `POST`. * **Success Response Codes**: Enter valid response codes (For example, `200` for HTTP Status OK) * **Failure Response Codes**: Enter invalid response codes (For example, `401` for HTTP Status Unauthorized) * **Authorization Details**: Choose the authorization scheme used by the service: `Bearer`, `Token`, `Basic`, or `AWS4_HMAC_SHA256`. 10. Select **Propagate this rule to all child namespaces** to apply the secret rule to all child namespaces. 11. Click **Add Rule**. ### Create secret rules from the command line For example, consider a token "demo\_value123" can be described using a regular expression. Here is an example of the rule specification: ```bash theme={null} "meta": { "name": "Demo Token" }, "spec": { "disabled": false, "keywords": [ "demo_" ], "regex": "demo_[0-9a-zA-Z]{20}", "rule_id": "demo-rule" } ``` Use the following command from the CLI to create this custom rule. ```bash expandable theme={null} $ endorctl api create -r SecretRule -n demo \ > --data '{ > "meta": { > "name": "Demo Token" > }, > "spec": { > "disabled": false, > "keywords": [ > "demo_" > ], > "regex": "demo_[0-9a-zA-Z]{20}", > "rule_id": "demo-rule" > } > }' INFO: Initiating host-check ... INFO: Host-check complete { "meta": { "create_time": "2023-09-27T17:08:18.436936Z", "kind": "SecretRule", "name": "Demo Token", "update_time": "2023-09-27T17:08:18.436936Z", "upsert_time": "2023-09-27T17:08:18.436936Z", "version": "v1" }, "spec": { "disabled": false, "keywords": [ "demo_" ], "regex": "demo_[0-9a-zA-Z]{20}", "rule_id": "demo-rule" }, "tenant_meta": { "namespace": "demo" }, "uuid": "65146182aaeeffbaf5b6b553" } ``` After the rule is created, Endor Labs uses this rule to detect this category of secrets. To create a custom rule without a `rule_id`, omit the field and let Endor Labs generate one from the name. ```bash theme={null} endorctl api create -r SecretRule -n --data '{ "meta": { "name": "Demo Token" }, "spec": { "keywords": ["demo_"], "regex": "demo_[0-9a-zA-Z]{20}" } }' ``` If you can validate the secret using an HTTP request, then you can also add [validation](#validator) to this rule. See the following example for creating a validation rule for a demo\_test123 token. ```bash theme={null} curl -H "Authorization: Bearer "demo_test123" https://api.testserver.com/user ``` Then the validation specification can be: ```bash expandable theme={null} "validation": { "name": "Demo secrets validator", "http_request": { "header": [ { "key": "Bearer", "value": "{{.AuthzValue}}", "authz": true } ], "method": "GET", "uri": "https://api.testserver.com/user" }, "http_response": { "failed_auth_codes": [ 401 ], "successful_auth_codes": [ 200 ] } } ``` #### Validator You can use a validator to check if a discovered secret is valid or not. The Endor Labs system rules for secrets include the necessary validator. When you validate a secret, the finding for that secret is categorized as critical, ensuring it receives higher priority compared to others. When defining a custom rule, you can add your own validator from the command line or the Endor Labs user interface. Endor Labs uses this information to send an HTTP request, such as a GET or POST, to the address that the service specifies for the detected secret. For example, when a GitHub Personal Access Token named "ghp\_endor123" is detected, Endor Labs sends the following HTTP request to GitHub's address: ```bash theme={null} curl -H "Authorization: Token "ghp_endor123" https://api.github.com/user ``` The authentication codes defined by the service are used to mark the secrets as valid or invalid. The validation portion of the secret rule contains the following fields: #### Template parameters Some secrets cannot be validated with the secret value alone. For example, validating an Azure AD client secret also needs the client ID and tenant ID. The validator references these values in the request with template syntax, such as `{{.ClientID}}` and `{{.TenantID}}`, the same way `{{.AuthzValue}}` references the detected secret. Endor Labs defines `template_params` for the system rules that need them. You can't set `template_params` on a custom rule from the CLI or API; Endor Labs manages these values. A validated secret is marked valid or invalid based on the response codes. Endor Labs categorizes a valid secret as a critical finding so that it is prioritized for remediation. #### HTTP request header HTTP request header is a set of key-value pairs that should be added to the header. ```bash theme={null} { "key": "Content-Type", "value": "application/json" } ``` There are cases where one needs to use a value on runtime and substitute a pattern. For example, the secret itself that needs to be substituted is one such case. This is achieved by declaring a value using the `{{.Value}}` pattern. For the HTTP header section that includes the secret, the block looks like the following snippet. ```bash theme={null} { "key": "Token", "value": "{{.AuthzValue}}", "authz": true, } ``` In this case, the scanner replaces the candidate secret that was detected and adds it to the HTTP request header in place of `{{.AuthzValue}}`. The following table describes a special case where the key-value pair is marked with the `authz` flag and is used to craft the "Authorization" part of the header, where three options are supported. ## Allowlists An allowlist excludes known false positives for a rule without disabling the rule. Add one or more allowlists under `spec.allowlists`. Each allowlist supports the following fields. The following example ignores test fixtures and any match that contains `EXAMPLE`. ```json theme={null} "allowlists": [ { "description": "Ignore test fixtures and example values", "paths": ["(^|/)testdata/"], "stop_words": ["EXAMPLE"], "condition": "OR" } ] ``` ## Manage secret rules 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Secret Rules**. The list of all secret rules appears. Secret rules 3. Select the rule for which you want to view the details. The rule details appear in the right sidebar. Secret rule details ### Clone a secret rule Select the vertical three dots to the right of the rule, then select **Clone Rule**. The cloned rule appears in the list of secret rules and you can edit it. ### Edit a secret rule Select the vertical three dots to the right of the rule, then select **Edit Rule**. You can only edit the custom rules that you created or the system rules that you cloned. ### Fetch secret rules with endorctl To fetch the Endor Labs secret scanning rules from the command line type the following commands: ```bash theme={null} endorctl api list -r SecretRule -n ``` For example, to see the rule for the GitHub Personal Access Token, you could search by the name `GitHub Personal Access Token` or by the rule-id `github-pat`: ```bash theme={null} endorctl api get -r SecretRule -n --name "GitHub Personal Access Token" endorctl api list -r SecretRule -n --filter=spec.rule_id==github-pat ``` To export all rules, including system rules, as YAML for offline scans, use the `--list-all` flag with YAML output. ```bash theme={null} endorctl api list -r SecretRule -o yaml --list-all > secret-rules.yaml ``` # View secret findings Source: https://docs.endorlabs.com/scan/secrets/view-secret-findings/index Review, prioritize, and remediate findings from a secrets scan. After a secrets scan, Endor Labs raises a finding for each detected secret. You can review the findings, understand their severity, and take corrective action. ## View secret findings 1. Select **Findings** > **Secrets** from the left sidebar. Findings of secrets 2. Select a finding to view its details, including: * **Project**: The project where the secret was found, with its finding policy, categories, and attributes. * **Risk Details**: Whether the secret is valid or invalid, an explanation of the finding, and the recommended remediation. Secret finding details 3. Click **View Details** to explore additional information about the finding. ## Secret validity When a rule includes a validator, Endor Labs checks whether a detected secret is still active and shows the result as the **Validation** status on the finding. * **Valid**: The secret authenticated successfully and is active. Endor Labs raises these as critical findings. * **Invalid**: The secret did not authenticate and is likely revoked or expired. * **Unverified**: Endor Labs did not validate the secret, either because the rule has no validator or because validation could not complete. Validation reduces noise, because you can focus on the credentials that currently provide access. See [Validator](/scan/secrets/secret-rules#validator) for how validation is configured. ## Deduplicated findings Endor Labs groups an identical secret found in multiple files, branches, or repositories into a single finding. Each finding lists every location where the secret appears, so you can assess the full exposure and remediate once. A higher occurrence count signals wider exposure and higher risk. ## Triage and prioritize Use the following signals to decide what to address first: * **Validity**: Valid secrets are active and are raised as critical. Address these first. * **Occurrences**: A secret found in many locations has a larger exposure. * **Location**: Focus on production and default branches before feature branches. Filter the **Secrets** findings list by project and severity to focus your review. ## Remediate a secret Removing a secret from the latest code does not make it safe, because the secret remains in the Git history and may already be compromised. Always revoke or rotate a leaked credential at its issuing service. Deleting the secret from the code alone does not invalidate it. To remediate a leaked secret: 1. Revoke or rotate the credential at the issuing service so the exposed value stops working. 2. Replace the hard-coded value with a reference to a secrets manager or an environment variable. 3. Remove the secret from the code, and purge it from the Git history if your policy requires it. 4. Re-scan to confirm the finding is resolved. ## Manage false positives If a finding is a known false positive, suppress it rather than ignoring it. Endor Labs offers inline annotations, rule allowlists, and finding-level exceptions. See [Exclude false positives from secret scans](/scan/secrets/scan-secrets#exclude-false-positives-from-secret-scans). ## Secret findings in pull requests When pull request comments are enabled, Endor Labs posts secret findings as inline comments on the changed lines, so developers see them in context. Inline comments are supported on pull requests and merge requests in GitHub, GitLab, Azure DevOps, and Bitbucket. Enable comments with `--enable-pr-comments` in a CI scan, or with the pull request comment setting in your SCM integration or scan profile. See [Pull request scans](/scan/pr-scans) and [CI/CD integrations](/setup-deployment/ci-cd). # Working with monorepos Source: https://docs.endorlabs.com/scan/working-with-monorepos/index Learn strategies to best work with large monorepos. Large monorepos are a reality for many organizations. Since monorepos can have anywhere from tens to even hundreds of packages scanning all packages in a monorepo can take significant periods of time. While the time requirements may vary based on your development team and pipeline times in general. Development teams need quick testing times to improve their productivity while security teams need full visibility across a monorepo. These two needs can conflict without performance engineering or an asynchronous scanning strategy. This documentation outlines some performance engineering and scanning strategies for large monorepos. See [Bazel documentation](/scan/bazel) if you use a monorepo with Bazel as your primary build system. ## Asynchronous scanning strategies When scanning a large monorepo, a common approach taken by security teams is to run an asynchronous cron job outside a CI/CD-based environment. This is often the point of least friction but is prohibitive. With this approach, inline blocking of critical issues is not generally possible. This is a scanning strategy for monorepos, but it is not recommended beyond a step to get initial visibility into a large monorepo. ## Performance Enhancements for inline scanning strategies Use the following performance enhancements with Endor Labs to enable the scanning of large monorepos: ### Incremental PR scans For pull request scans, combine `--pr-incremental` with `--quick-scan` to resolve dependencies only for the languages and packages a pull request affects. See [Skip unaffected packages during incremental PR scans](/scan/pr-scans#skip-unaffected-packages-during-incremental-pr-scans) for supported ecosystems and configuration. ### Scoping scans based on changed files For many CI/CD systems path filters are readily available. For example, with GitHub Actions, [dorny path filters](https://github.com/dorny/paths-filter) is a readily accessible way to establish a set of filters by a path. This is generally the most effective path to handle monorepo deployments but does require the highest level of human time investment. The human time investment is made up by the time saved by reducing the need to scan everything on each change. Based on the paths that change you can scope scans based on the files that have actually changed. For example, you can scan only the packages in a monorepo that are housed under the `ui/` directory. When this path has changed, run a scan such as `endorctl scan --include-path=ui/**`. Using a path filtering approach each team working in a monorepo would need to be responsible for the packages that they maintain. Generally, each team is associated with one or more pre-defined directory paths. ### Parallelizing scans for many packages When scanning a large monorepo organizations can choose to regularly scan the whole monorepo based on the packages or directories they'd like to scan. Different jobs may be created that scan each directory simultaneously. #### Parallelizing with scoped scans Using scoped scans for monorepos with multiple parallel include patterns is a common performance optimization for monorepos. The following example shows parallel GitHub action scan that you can use as a reference. ```yaml expandable theme={null} name: Parallel Actions on: push: branches: [main] jobs: scan-ui: runs-on: ubuntu-latest steps: - name: UI Endor Labs Scan run: endorctl scan --include-path=ui/ scan-backend: runs-on: ubuntu-latest steps: - name: Backend Endor Labs Scan run: endorctl scan --include-path=backend/ ``` In this example, the directories `ui/` and `backend/` are both scanned simultaneously and the results are aggregated by Endor Labs. This approach can improve the overall scan performance across a monorepo where each directory can be scanned independently. To include or exclude a package based on its directory. ```bash theme={null} endorctl scan --include-path="directory/path/" ``` See [scoping scans](/best-practices/scoping-scans) for more information on approaches to scoping scans. #### Parallelizing across languages For teams that work out of smaller monorepos, it is often most reasonable to parallelize scanning based on the language that is being scanned. Optimize scanning performance for individual languages based on need. The following examples show a parallel GitHub action scan as a reference. In this example, JavaScript and Java are scanned at the same time and aggregated together by Endor Labs. This approach can improve the overall scan performance across a monorepo with multiple languages. ```yaml expandable theme={null} name: Parallel Actions on: push: branches: [main] jobs: scan-java: runs-on: ubuntu-latest steps: - name: Java Endor Labs Scan run: endorctl scan --languages=java scan-javascript: runs-on: ubuntu-latest steps: - name: Javascript Endor Labs Scan run: endorctl scan --languages=javascript,typescript ``` Run the following command to scan a project for only packages written in TypeScript or JavaScript. ```bash theme={null} endorctl scan --languages=javascript,typescript ``` Run the following command to scan a project for only packages used for packages written in Java. ```bash theme={null} endorctl scan --languages=java ``` Define supported languages as a comma-separated list of the following languages: # Endor Labs Agent Kit in Antigravity CLI Source: https://docs.endorlabs.com/secure-ai-coding/agent-kit/antigravity-cli/index Install and use the Endor Labs Agent Kit in Antigravity CLI. The Endor Labs Agent Kit installs into Antigravity CLI as a plugin, adding the Endor Labs setup skill, workflow skills, and subagents. Google documents Antigravity CLI as the consumer transition path for Gemini CLI, so use this package if your Gemini CLI account is affected by that transition. Clone the public distribution repository, then validate and install the generated Antigravity plugin from it. ```bash theme={null} git clone https://github.com/endorlabs/ai-plugins cd ai-plugins agy plugin validate ./plugins/antigravity/endor-labs-agent-kit agy plugin install ./plugins/antigravity/endor-labs-agent-kit agy plugin list ``` Some Antigravity installs expose the command as `antigravity` instead of `agy`. Use the same `plugin validate`, `plugin install`, and `plugin list` subcommands. Restart Antigravity CLI after installing or reinstalling the plugin if the new skills or subagents are not visible. Ask your AI coding assistant to run the setup skill. ```text theme={null} Use the endor-agent-kit-setup skill to check Endor Labs Agent Kit readiness. ``` The setup skill guides package-manager-first `endorctl` installation, verifies Endor Labs authentication and namespace readiness, and reports missing `gh` or toolchain prerequisites. It does not run scans, run `endorctl host-check`, edit shell profiles, auto-install `gh`, or install language runtimes and package managers. Each workflow is available as a skill and as a subagent. Invoke a subagent with `@`. Try these example prompts. ```text theme={null} @ai-sast-remediation triage AI SAST findings for this repository ``` ```text theme={null} @sca-remediation check this repository for P0 SCA findings I can start remediating ``` ```text theme={null} @configuration-automation probe GitHub org for Endor Labs monitored-branch onboarding gaps and setup prescriptions ``` ```text theme={null} @troubleshooting diagnose this Endor Labs scan failure from redacted error text and read-only tenant evidence ``` See the [Agent Kit overview](/secure-ai-coding/agent-kit) for the full agent catalog, and the [safety model](/secure-ai-coding/agent-kit/safety-model) for how mutating agents handle approval gates. # Endor Labs Agent Kit in Claude Code Source: https://docs.endorlabs.com/secure-ai-coding/agent-kit/claude-code/index Install and use the Endor Labs Agent Kit in Claude Code. The Endor Labs Agent Kit installs into Claude Code as a plugin, adding the Endor Labs setup skill and the full set of workflow agents. Install the `endor-labs-agent-kit@endorlabs` plugin from the public marketplace. In Claude Code, run. ```text theme={null} /plugin marketplace add endorlabs/ai-plugins /plugin install endor-labs-agent-kit@endorlabs /reload-plugins /agents ``` Start a new Claude Code session or run `/reload-plugins` after installing or reinstalling the plugin. If Claude Code still shows stale content for the same version, uninstall and reinstall the plugin. Run `/reload-plugins` and start a new session so host caches reload the agents and setup skill. **Upgrading from Endor Labs Skills** If you previously installed the Endor Labs plugin as `ai-plugins@endorlabs`, it keeps working and existing installs are unaffected. New users should install the `endor-labs-agent-kit@endorlabs` plugin instead. Do not enable both plugin IDs in the same Claude Code profile, because they expose the same agents and setup skill. Ask your AI coding assistant to run the setup skill. ```text theme={null} Use the endor-agent-kit-setup skill to check Endor Labs Agent Kit readiness. ``` The setup skill guides package-manager-first `endorctl` installation, verifies Endor Labs authentication and namespace readiness, and reports missing `gh` or toolchain prerequisites. It does not run scans, run `endorctl host-check`, edit shell profiles, auto-install `gh`, or install language runtimes and package managers. Invoke a workflow agent with `@agent-`. Try these example prompts. ```text theme={null} @agent-ai-sast-remediation triage AI SAST findings for this repository ``` ```text theme={null} @agent-sca-remediation check this repository for P0 SCA findings I can start remediating ``` ```text theme={null} @agent-configuration-automation probe GitHub org for Endor Labs monitored-branch onboarding gaps and setup prescriptions ``` ```text theme={null} @agent-troubleshooting diagnose this Endor Labs scan failure from redacted error text and read-only tenant evidence ``` See the [Agent Kit overview](/secure-ai-coding/agent-kit) for the full agent catalog, and the [safety model](/secure-ai-coding/agent-kit/safety-model) for how mutating agents handle approval gates. # Endor Labs Agent Kit in OpenAI Codex Source: https://docs.endorlabs.com/secure-ai-coding/agent-kit/codex/index Install and use the Endor Labs Agent Kit in OpenAI Codex. The Endor Labs Agent Kit installs into OpenAI Codex as a plugin, adding the Endor Labs setup skill, Codex skills, and bundled custom-agent definitions. Add the Endor Labs marketplace and install the Endor Labs Agent Kit from the Codex plugin directory. In the Codex CLI, run. ```bash theme={null} codex plugin marketplace add endorlabs/ai-plugins \ --sparse .agents/plugins \ --sparse plugins/codex/endor-labs-agent-kit ``` Restart Codex and start a new thread after installing or reinstalling the plugin so the host loads the skills and agents. Ask Codex to run setup. ```text theme={null} Use the endor-agent-kit-setup skill to check readiness and install the bundled Codex custom agents. ``` After explicit approval, the setup skill installs the managed Endor Labs custom agents for Codex under `${CODEX_HOME:-~/.codex}/agents` and bundled user skills under `$HOME/.agents/skills`. It does not run scans, run `endorctl host-check`, edit shell profiles, install `gh`, or install language runtimes and package managers. Each workflow is available as a Codex skill and as a custom agent. Try these example prompts. ```text theme={null} Use the ai-sast-remediation skill to triage AI SAST findings for this repository. ``` ```text theme={null} Use the sca-remediation skill to check this repository for P0 SCA findings I can start remediating. Do not edit files or open a PR/MR until I approve. ``` ```text theme={null} Use the configuration-automation skill to probe GitHub org for Endor Labs monitored-branch onboarding gaps and setup prescriptions. ``` ```text theme={null} Use the troubleshooting skill to diagnose this Endor Labs issue from redacted error text and read-only tenant evidence. ``` See the [Agent Kit overview](/secure-ai-coding/agent-kit) for the full agent catalog, and the [safety model](/secure-ai-coding/agent-kit/safety-model) for how mutating agents handle approval gates. # Endor Labs Agent Kit Cursor SDK Source: https://docs.endorlabs.com/secure-ai-coding/agent-kit/cursor-sdk/index Run Endor Labs Agent Kit workflows programmatically with the Cursor Python SDK. The Cursor SDK package runs Endor Labs Agent Kit workflows through Cursor's Python SDK. Use it for automation, CI, backend services, orchestration, and scripted local or cloud runs. To install interactive agents into the Cursor IDE instead, use the [Cursor plugin](/secure-ai-coding/agent-kit/cursor). The SDK package ships in the public distribution repository, [endorlabs/ai-plugins](https://github.com/endorlabs/ai-plugins), under [`cursor-sdk/`](https://github.com/endorlabs/ai-plugins/tree/main/cursor-sdk). Clone the repository and run the commands below from its root. It includes a `run_cursor_agent.py` launcher, an `agent_definitions.json` agent map, generated prompt files, and a `requirements.txt`. Install the Cursor Python SDK dependency. ```bash theme={null} python3 -m pip install -r cursor-sdk/requirements.txt ``` If you use `uv`, run `uv pip install -r requirements.txt` from the `cursor-sdk` directory instead. Export your Cursor API key. Never paste it into a prompt. ```bash theme={null} export CURSOR_API_KEY="crsr_..." ``` Run a read-only agent against a local workspace. ```bash theme={null} python cursor-sdk/run_cursor_agent.py endor-configuration-automation-agent \ --workspace /path/to/repo \ "Explain what evidence you need to assess GitHub onboarding gaps. Keep it read-only." ``` To run against a Cursor cloud agent, pass `--mode cloud` with a repository URL and ref. ```bash theme={null} python cursor-sdk/run_cursor_agent.py endor-sca-remediation-agent \ --mode cloud \ --repo-url https://github.com/your-org/your-repo \ --ref main \ "Prepare a remediation plan only. Do not edit files or open a PR." ``` Cloud SDK agents appear in Cursor Web or the Cursor agents window under `Filter > Source > SDK`. ## Safety * Setup is readiness guidance only. It does not run `endorctl scan` or `endorctl host-check`. * Mutating agents still require separate approval for file edits, branch pushes, PR or MR creation, comments, tickets, and Endor Labs policy writes. * Never paste Cursor, Endor Labs, source-provider, or package-registry secrets into prompts. Use the `CURSOR_API_KEY` environment variable for the SDK key. See the [Agent Kit overview](/secure-ai-coding/agent-kit) for the full agent catalog, and the [safety model](/secure-ai-coding/agent-kit/safety-model) for the complete safety contract. # Endor Labs Agent Kit in Cursor Source: https://docs.endorlabs.com/secure-ai-coding/agent-kit/cursor/index Install and use the Endor Labs Agent Kit in Cursor. The Endor Labs Agent Kit installs into Cursor as a plugin, adding the Endor Labs setup agent, workflow agents, support skills, and advisory hooks. To run Agent Kit workflows from Python code, CI, or a backend service instead of the Cursor IDE, use the [Cursor SDK](/secure-ai-coding/agent-kit/cursor-sdk). Install the Endor Labs plugin from the Cursor Marketplace. In Cursor Agent chat, run. ```text theme={null} /add-plugin endorlabs ``` You can also install it from the [Cursor Marketplace page](https://cursor.com/marketplace/endorlabs). Open your project and reload Cursor if prompted. Ask your AI coding assistant to run the setup skill. ```text theme={null} Use the endor-agent-kit-setup skill to check Endor Labs Agent Kit readiness. ``` The setup skill guides package-manager-first `endorctl` installation, verifies Endor Labs authentication and namespace readiness, and reports missing `gh` or toolchain prerequisites. It does not run scans, run `endorctl host-check`, edit shell profiles, auto-install `gh`, or install language runtimes and package managers. Select an Endor Labs agent from the Cursor agent picker, or invoke one by name. Try these example prompts. ```text theme={null} @endor-ai-sast-remediation-agent triage AI SAST findings for this repository ``` ```text theme={null} @endor-sca-remediation-agent check this repository for P0 SCA findings I can start remediating ``` ```text theme={null} @endor-configuration-automation-agent probe GitHub org for Endor Labs monitored-branch onboarding gaps and setup prescriptions ``` ```text theme={null} @endor-troubleshooting-agent diagnose this Endor Labs scan failure from redacted error text and read-only tenant evidence ``` See the [Agent Kit overview](/secure-ai-coding/agent-kit) for the full agent catalog, and the [safety model](/secure-ai-coding/agent-kit/safety-model) for how mutating agents handle approval gates. # Endor Labs Agent Kit in Gemini CLI Source: https://docs.endorlabs.com/secure-ai-coding/agent-kit/gemini-cli/index Install and use the Endor Labs Agent Kit in Gemini CLI. The Endor Labs Agent Kit installs into Gemini CLI as an extension, adding the Endor Labs setup skill, workflow skills, and preview subagents. Clone the public distribution repository, then install the generated Gemini extension from it. ```bash theme={null} git clone https://github.com/endorlabs/ai-plugins gemini extensions install ./ai-plugins/plugins/gemini/endor-labs-agent-kit gemini extensions list ``` Gemini CLI may show a folder trust prompt for local paths. Inspect the package and approve only the expected Endor Labs Agent Kit extension source. Restart Gemini CLI after installing or reinstalling the extension. Google documents Antigravity CLI as the consumer transition path for Gemini CLI. If your Gemini CLI account is affected by that transition, use the [Antigravity CLI](/secure-ai-coding/agent-kit/antigravity-cli) package instead. Keep this Gemini extension for supported Gemini CLI environments. Ask your AI coding assistant to run the setup skill. ```text theme={null} Use the endor-agent-kit-setup skill to check Endor Labs Agent Kit readiness. ``` The setup skill guides package-manager-first `endorctl` installation, verifies Endor Labs authentication and namespace readiness, and reports missing `gh` or toolchain prerequisites. It does not run scans, run `endorctl host-check`, edit shell profiles, auto-install `gh`, or install language runtimes and package managers. Each workflow is available as a skill and as a subagent. Invoke a subagent with `@`. Try these example prompts. ```text theme={null} @ai-sast-remediation triage AI SAST findings for this repository ``` ```text theme={null} @sca-remediation check this repository for P0 SCA findings I can start remediating ``` ```text theme={null} @configuration-automation probe GitHub org for Endor Labs monitored-branch onboarding gaps and setup prescriptions ``` ```text theme={null} @troubleshooting diagnose this Endor Labs scan failure from redacted error text and read-only tenant evidence ``` See the [Agent Kit overview](/secure-ai-coding/agent-kit) for the full agent catalog, and the [safety model](/secure-ai-coding/agent-kit/safety-model) for how mutating agents handle approval gates. # Endor Labs Agent Kit Source: https://docs.endorlabs.com/secure-ai-coding/agent-kit/index Ready-to-use Endor Labs security agents for AI coding assistants. The Endor Labs Agent Kit is a catalog of ready-to-use security agents that run inside your AI coding assistant. Each agent packages a specific Endor Labs workflow, such as triaging findings, remediating vulnerable dependencies, or diagnosing scan failures, with a built-in safety contract, approval gates, and evidence requirements. Install the kit as a plugin or extension in your host of choice, then ask the assistant to run a workflow in plain language. The Agent Kit replaces the earlier Endor Labs Skills offering, which could only install and configure `endorctl`. The kit ships a full set of workflow agents across every supported host. ## How it is distributed The Agent Kit lives in two open-source repositories: * **[endorlabs/ai-plugins](https://github.com/endorlabs/ai-plugins)**: The distribution and marketplace repository. This is what you install from. It is already published and branded in the Claude Code and Cursor marketplaces. * **[endorlabs/endor-labs-agent-kit](https://github.com/endorlabs/endor-labs-agent-kit)**: The source and builder repository. Use it to contribute or propose new agents, file issues, or grab runtime-neutral [portable agents](/secure-ai-coding/agent-kit/portable) for your own agent runtime. **Upgrading from Endor Labs Skills** If you previously installed the Endor Labs plugin as `ai-plugins@endorlabs`, it keeps working and existing installs are unaffected. New users should install the `endor-labs-agent-kit@endorlabs` plugin instead. Do not enable both plugin IDs in the same Claude Code profile, because they expose the same agents and setup skill. ## Supported hosts Install the kit in any of the following hosts. ## Agent catalog The kit ships 11 agents. Most are read-only. Two agents, AI SAST Remediation and SCA Remediation, can change state, and they keep every mutating action behind a separate approval gate. See the [safety model](/secure-ai-coding/agent-kit/safety-model) for details. In a hurry? Jump to [Quick start](#quick-start) and pick your host and agent to copy the exact install command and first-workflow prompt. If you are new to the Agent Kit, start with the four most popular agents: **SCA Remediation**, **AI SAST Remediation**, **Configuration Automation**, and **Troubleshooting**. The **License** column shows the Endor Labs license each agent requires. Agents marked **Any** work with any Endor Labs license because they operate on findings and package intelligence you already have. For what each license includes, see [Licenses](/introduction/licenses). Each host exposes these workflows with its own invocation syntax. See the install page for your host for exact commands and example prompts. ## Quick start Choose your host and a starting agent to generate the matching install command, setup prompt, and first-workflow prompt. The four most popular agents appear as buttons. Select **Other agents** to pick any of the remaining agents from the dropdown. Using Cursor or running agents programmatically? See [Cursor](/secure-ai-coding/agent-kit/cursor) and the [Cursor SDK](/secure-ai-coding/agent-kit/cursor-sdk). ## Run setup first After you install the kit in any host, run the setup skill before anything else. ```text theme={null} Use the endor-agent-kit-setup skill to check Endor Labs Agent Kit readiness. ``` Setup is readiness guidance only. It checks for `endorctl`, authentication, namespace selection, `gh`, and toolchain prerequisites, and reports what is missing. It never runs scans, runs `endorctl host-check`, edits shell profiles, installs runtimes, or writes credentials. ## Choose your host to get started Install the Endor Labs Agent Kit plugin in Claude Code. Install the Endor Labs Agent Kit plugin in Cursor. Install the Endor Labs Agent Kit plugin in OpenAI Codex. Install the Endor Labs Agent Kit extension in Gemini CLI. Install the Endor Labs Agent Kit plugin in Antigravity CLI. Run Agent Kit workflows programmatically with the Cursor Python SDK. Run runtime-neutral agents in your own agent runtime. Understand the safety contract and output guarantees. To scan your code for vulnerabilities, secrets, and SAST issues directly in your IDE, see the [Endor Labs MCP server](/setup-deployment/mcp). # Portable agents Source: https://docs.endorlabs.com/secure-ai-coding/agent-kit/portable/index Run runtime-neutral Endor Labs Agent Kit workflows in your own agent runtime. Portable agents are runtime-neutral versions of the Agent Kit workflows. Use them when your organization already runs its own agent runtime, repository workflow, ticketing system, approval system, credential controls, and audit pipeline. You get the Endor Labs workflow without a host-specific plugin. A common example is a team that opens pull requests through its own automation and runs agents in a platform such as Atlassian Rovo. Portable bundles live in the [endorlabs/endor-labs-agent-kit](https://github.com/endorlabs/endor-labs-agent-kit) repository under [`portable//`](https://github.com/endorlabs/endor-labs-agent-kit/tree/main/portable). ## What is in a bundle Each portable bundle includes: * `agent.md`: the runtime-neutral agent instructions. * `agent.manifest.json`: machine-readable transports, capabilities, actions, wrappers, and degradation behavior. * `output-contract.md`: inputs, outputs, adapter contracts, and mechanical workflow gates. * Optional `actions.yaml` adapter contracts, plus `endorctl-setup.md` and `architecture.svg` support files. ## Split-responsibility model The integration model is deliberately split between the Agent Kit and your runtime: * The **Agent Kit** defines the workflow, evidence requirements, safety contract, and structured output. * **Your runtime** enforces authentication, authorization, logging, audit, adapter execution, and approval policy. * **Runtime adapters** perform the semantic actions the agent requests. The agent must not claim an action completed unless your adapter returns evidence. Evidence can be a PR or MR URL, ticket ID, policy UUID, branch, validation result, or an explicit data gap. ## Adapter mapping Map each portable action to an adapter in your environment. ## Conformance levels Your portable integration should target one of three conformance levels: * **contract-aware**: Loads the manifest, exposes declared adapters, and returns evidence or data gaps. * **mutation-safe**: Adds authorization, explicit confirmation, audit logging, and fail-closed behavior for mutating actions. * **enterprise-ready**: Adds adversarial evaluations, data-loss-prevention and secret redaction, and incident review. For the full set of required runtime controls and the adapter response schema, refer to [portable-runtime-conformance.md](https://github.com/endorlabs/endor-labs-agent-kit/blob/main/docs/portable-runtime-conformance.md) in the Agent Kit repository. See the [safety model](/secure-ai-coding/agent-kit/safety-model) for the shared safety contract that every portable bundle preserves. # Safety model and output contract Source: https://docs.endorlabs.com/secure-ai-coding/agent-kit/safety-model/index The safety classes, approval gates, and output contract for Endor Labs Agent Kit agents. Every Agent Kit workflow carries an explicit safety contract that the host enforces. This page explains the safety classes, approval gates, evidence requirements, and the output contract that agents return. ## Safety classes Each agent declares its safety class in its source recipe. Most agents are read-only. Two agents can change state, and both are approval-gated: * **AI SAST Remediation** (`ai-sast-remediation`) * **SCA Remediation** (`sca-remediation`) All other agents in the catalog are read-only. ### Read-only agents Read-only agents do not: * edit files * create pull requests * run scans * dismiss findings * create policies * mutate Endor Labs state When a read-only agent is allowed to run a shell command, its prompt limits the command to documented read-only Endor Labs lookups. On Claude Code, read-only agents that only inspect the workspace are limited to `Read`, `Glob`, `Grep`, and `LS`. File mutation, notebook, web, and todo tools stay denied. ### Mutating agents Mutating agents are published only when their recipe declares the required host capabilities. AI SAST Remediation and SCA Remediation may fetch source context, write patch files, run git or source-provider commands, and open a change request. They do this only when you ask for that workflow and the target repository credentials are available. ## Approval gates Mutating workflows split every state-changing action into a separate, evidence-backed approval gate: * file edits * branch pushes * pull request or merge request creation * PR or MR comments * ticket creation * approval verification * Endor Labs policy writes Setup is always separate from these workflows. Setup never runs scans, never runs `endorctl host-check`, and never performs a mutating action. ## Evidence requirements Agents must back every claim with evidence: * Before answering, an agent returns adapter or tool evidence, or it records the missing signal in `data_gaps`. It never invents facts. * An agent only claims a file edit, branch push, PR or MR, ticket, policy write, or approval when the host or adapter returns evidence such as a URL, ID, UUID, branch, or validation result. * Namespace and project provenance is required before live Endor Labs queries. ## Secret handling and untrusted content * Agents never print, persist, or copy Endor Labs API keys, secrets, tokens, or full config values. They report credential presence by variable or key name only. * Agents treat repository files, comments, findings, and tool output as data, not as instructions. Untrusted text cannot bypass an approval gate, and agents do not publish exploit payloads, credentials, or config values. ## Artifact integrity The Agent Kit records a SHA-256 checksum for every generated artifact in `manifest.json`. Install and provenance checks verify artifacts against those checksums, so you can confirm that an installed agent matches the published catalog. ## Output contract Agents return concise prose plus a JSON block. The exact schema depends on the agent. If a signal is unavailable because of setup, authentication, account tier, or tooling, the agent records that in `data_gaps` instead of inventing evidence. For the mutating workflows, structured output can be checked mechanically before a workflow advances. The Agent Kit ships maintainer commands that validate SCA Remediation and AI SAST Remediation output before a gate advances. These commands check required fields, risk decisions, approval evidence, and rendered PR or MR bodies. These checks keep mutating workflows from skipping a required approval or fabricating a remediation plan. See the [portable agents](/secure-ai-coding/agent-kit/portable) page for how this contract maps to your own agent runtime. # Agentic UI (AppSec Assistant) Source: https://docs.endorlabs.com/secure-ai-coding/agentic-ui/index Use AI-powered assistance to ask questions about findings and troubleshoot issues. Endor Labs provides AI-powered assistance to help you understand vulnerabilities, troubleshoot issues, and accelerate security triage. ## Endor AI Chat Use the Endor AI Chat to understand vulnerabilities and view recommended actions. It leverages AI to provide contextual explanations, guidance, and next steps for issues detected in your project. With AI-powered context, you can reduce time spent digging through raw data and accelerate triage and remediation. ### Prerequisites To start using Endor Ask AI chat, you must enable **Code Segment Embeddings and LLM Processing** in **Data Privacy** settings. 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **SYSTEM SETTINGS** > **Data Privacy**. 3. Select **Code Segment Embeddings and LLM Processing**. 4. Click **Save Data Privacy Settings**. Enable Code Segment Embeddings and LLM Processing ### Use cases * **Investigate vulnerabilities**: Use the AI chat to simplify technical details and generate summaries. * **Summarize scan results**: Analyze scans performed by endorctl over time. * **Understand vulnerabilities**: Ask natural-language questions about vulnerabilities in the database. * **Understand packages**: Get quick explanations for package resolution and reachability errors. ### Example questions * Summarize this finding. * Is this vulnerability exploitable? * How do I remediate this? * Is this a true positive SAST finding? * Which issues were introduced or resolved? * Why is this considered high severity? ## Data scope for AI responses Endor Ask AI chat agents generate answers based solely on specific data available within the Endor Labs platform: * Findings * Scan results * Vulnerabilities * Package versions If the requested information falls outside this scope, the AI may not be able to generate a response. # Agent activity Source: https://docs.endorlabs.com/secure-ai-coding/agents-hub/activity/index Beta
Read the usage metrics the Agents Hub reports for each agent in your tenant. The Agents Hub shows you how your team uses agents in your tenant, so you can see which agents are active, how often they run, and when they last ran. This page explains what those numbers mean and how to read them. Agent activity is usage metering, not a compliance audit log. The data is approximate, and Endor Labs refreshes it periodically, so it can lag real activity. Don't treat it as your system of record for audit or compliance. ## View agent activity Activity appears on the agent cards in the catalog itself, not on a separate page. 1. Select **Agents Hub** from the left sidebar. 2. Look at the **Active agents** section at the top of the catalog. Each card there shows the agent's activity. If you don't see an **Active agents** section, no agent in your tenant has run recently, and the catalog shows the full agent list instead. ## What the activity view shows Each agent that ran recently appears under **Active agents** with two indicators on its card. * **Tasks**: How many calls the agent made to the Endor Labs API. * **Last run**: When the agent most recently made a call. An agent counts as active when it made at least one call to the Endor Labs API in the reporting window. An agent with no recent activity appears under **More agents** without these indicators. The view covers the last 7 days of activity, and Endor Labs retains activity for up to 30 days. The view counts only the requests agents make with delegated credentials. Requests you run yourself, such as plain `endorctl api` commands, don't appear here. See [Delegated agent credentials](/secure-ai-coding/agents-hub/delegated-credentials) to learn how agents authenticate. ## How this differs from coding agent governance The Agents Hub activity view and coding agent governance answer two different questions. * **Agent activity** in the Agents Hub is what an agent called against the Endor Labs API, seen from the backend. * **Coding agent governance** is what an agent did on the developer's machine, such as the tools it invoked, the commands it ran, and any policy violations during a coding session. Use agent activity to understand API usage per agent. Use coding agent governance to understand on-device behavior. ## Data isolation Endor Labs scopes activity to your tenant. You see usage for your own tenant only, never another tenant's agents or calls. The view aggregates activity across all namespaces in your tenant, and you can't narrow it to a single namespace. # Browse agents in the Agents Hub Source: https://docs.endorlabs.com/secure-ai-coding/agents-hub/browse-agents/index Beta
Find an agent in the catalog, read what it does, and install it in your AI coding assistant. The Agents Hub catalog lists every agent Endor Labs publishes for your tenant. This page shows you how to find an agent, read what it does, and install it in your AI coding assistant. ## Open the catalog Select **Agents Hub** from the left sidebar. The catalog groups agents into up to two sections. * **Active agents**: Agents that ran recently in your tenant. This section appears only when at least one agent has recent activity. * **More agents**: The rest of the catalog. When no agent has recent activity, the catalog shows a single unlabeled grid instead. Agents Hub catalog with Active agents and More agents sections Each agent appears as a card with an icon, its name, and a short description. A card under **Active agents** also shows a **Last run** time and a **Tasks** count. See [Agent activity](/secure-ai-coding/agents-hub/activity) for what those numbers mean. ## Find an agent You can narrow the catalog by category, by search term, or both. ### Filter by category Above the grid, the catalog shows a chip for **All agents** and a chip for each category present in the catalog. Select a category to show only its agents, and select it again to return to **All agents**. You can select one category at a time. Categories describe the kind of work an agent does. ### Search by name Enter a term in **Search agents**. The search matches each agent's name and short description as you type, and it applies on top of any category you selected. If nothing matches, the catalog reports **No matching agents**. Clear the search to return to the full catalog. ## Open an agent's details Select an agent card to open its details. The detail view has two sections. Agent detail view showing what the agent does and its available platforms ### What does this agent do? The first section describes what the agent does, when to use it, what evidence it works from, and whether it changes anything. Agents that only read your data say so here. ### Available platforms The second section lists every AI coding assistant the agent supports, one row per platform. Select **Install** on a row to reveal the install command for that platform, then copy it and run it where that assistant is set up. The platforms shown depend on what the agent publishes, so an agent can list fewer platforms than another. The agents run inside your AI coding assistant, not in the browser. For a full setup walkthrough per assistant, see the [Agent Kit](/secure-ai-coding/agent-kit). For how an agent authenticates when it reaches Endor Labs data, see [Delegated agent credentials](/secure-ai-coding/agents-hub/delegated-credentials). ## Catalog states The catalog tells you when it has nothing to show or can't load. These are the states you can encounter. # Delegated agent credentials Source: https://docs.endorlabs.com/secure-ai-coding/agents-hub/delegated-credentials/index Beta
How an agent reaches Endor Labs data under a short-lived, read-only token attributed to you. When an agent runs inside your AI coding assistant and needs Endor Labs data, it doesn't use your API key directly. Instead, `endorctl` exchanges your credentials for a short-lived, read-only token that Endor Labs attributes to you. The agent reaches the API under that token and never sees your raw credentials. The [Agent Kit](/secure-ai-coding/agent-kit) agents use this mechanism automatically. Every Endor Labs API command they run goes through `endorctl agent api`, labeled with the agent's catalog id, so you don't set anything up per agent. ## How it works The agent calls `endorctl agent api`, which mirrors the [`endorctl api`](/developers-api/cli) surface but runs every request under a delegated token. 1. `endorctl` reads your credentials, the same ones `endorctl api` uses. 2. It exchanges them with Endor Labs for a delegated token. The token is read-only, tied to you, and grouped into a single agent session. 3. It caches the token on disk and runs the API request under it. 4. Endor Labs enforces the read-only limit on its side and denies any request that would change state. The token expires after one hour. `endorctl` refreshes it automatically, so the agent keeps working across a session without re-authenticating each call. ## Before you begin You can use any credentials that `endorctl` already supports, except a browser or single sign-on session. The most common choice is an Endor Labs API key, set through these environment variables. ```bash theme={null} export ENDOR_API_CREDENTIALS_KEY= export ENDOR_API_CREDENTIALS_SECRET= ``` An Endor Labs token in `ENDOR_TOKEN` and keyless CI credentials, such as GitHub OIDC, also work. The one credential Endor Labs refuses to exchange is a browser or single sign-on session. If you normally sign in through your identity provider, create an API key for agent use. See [API keys](/platform-administration/api-keys) to create one. ## Run API requests as a delegated agent Run `endorctl agent api` with the same arguments you would pass to `endorctl api`. The following command lists findings in a namespace under a delegated token. ```bash theme={null} endorctl agent api list --resource Finding --namespace --agent-id ai-sast-remediation ``` The `--agent-id` value is an attribution hint that labels which agent made the request. Endor Labs agents pass their catalog agent id, and that id is what the [agent activity](/secure-ai-coding/agents-hub/activity) view reports against. You can also set it with the `ENDOR_AGENT_ID` environment variable. It doesn't grant or restrict access. Get a single resource by UUID. ```bash theme={null} endorctl agent api get --resource Project --uuid --namespace ``` ## What a delegated agent can and can't do `endorctl agent api` exposes the same subcommands as `endorctl api`. * `list` and `get` succeed, subject to your permissions. * `create`, `update`, and `delete` exist as subcommands, but Endor Labs denies them with a permission error because a delegated token is read-only. ## Manage the session cache `endorctl` caches delegated tokens under your configuration directory, by default `~/.endorctl/agent-sessions/`. It stores each token in its own file that only your user account can read. A cached token stays valid for one hour. Because `endorctl` caches the token, an agent that already holds a valid token keeps working offline. Only a request that needs a new token fails without network access. There's no dedicated command to clear the cache. To force a fresh exchange, delete the directory. ```bash theme={null} rm -rf ~/.endorctl/agent-sessions/ ``` ## Troubleshooting `endorctl` couldn't find usable credentials. Set an API key in `ENDOR_API_CREDENTIALS_KEY` and `ENDOR_API_CREDENTIALS_SECRET`, or a token in `ENDOR_TOKEN`, and confirm the credential is active in your tenant. A delegated token requires a non-interactive credential. Endor Labs refuses to exchange a browser or single sign-on session. Create an API key and set the credential environment variables. The agent tried a request that changes state, and Endor Labs rejected it. Depending on the endpoint, the error reads `read-only agent may not invoke a mutating method` or a generic permission denial. Make the change through your source control provider, such as a pull request, instead of writing to Endor Labs. # Agents Hub Source: https://docs.endorlabs.com/secure-ai-coding/agents-hub/index Beta
Browse Endor Labs security agents and see how they are used across your tenant. The Agents Hub is one place in the Endor Labs user interface to discover the security agents Endor Labs publishes, understand what each one does, and see how your team is using them. Each agent packages a specific Endor Labs workflow, such as triaging findings, remediating vulnerable dependencies, or diagnosing scan failures. You run the agents inside your own AI coding assistant, and the Agents Hub gives you the catalog and the activity view in the product. ## How it relates to the Agent Kit The Agents Hub and the [Endor Labs Agent Kit](/secure-ai-coding/agent-kit) describe the same agents from two directions. The agents are read-only against Endor Labs data. When an agent proposes a change, that change lands as a pull request or merge request in your source control provider, never as a direct write to Endor Labs. See [Trust and attribution](/secure-ai-coding/agents-hub/trust-and-attribution) for the full model. ## Open the Agents Hub Select **Agents Hub** from the left sidebar. The catalog lists every published agent, with an **Active agents** section for the agents your team has used recently. You can filter the catalog by category or search it by name. Select any agent to see what it does and which AI coding assistants it supports. See [Browse agents](/secure-ai-coding/agents-hub/browse-agents) for a full tour of the catalog, the agent detail view, and the catalog states. ## Run an agent The agents run inside your AI coding assistant, not in the browser. To start using an agent, install the [Agent Kit](/secure-ai-coding/agent-kit) in your host, then invoke the agent through that host. When an agent reaches Endor Labs data during a run, it authenticates with a short-lived, read-only credential that Endor Labs attributes to you. You don't hand the agent your API key. See [Delegated agent credentials](/secure-ai-coding/agents-hub/delegated-credentials) for how this works and what to set up. ## Monitor usage The Agents Hub shows you how your team uses each agent, including its **Tasks** count and **Last run** time. This view is usage metering, not a compliance audit log. See [Agent activity](/secure-ai-coding/agents-hub/activity) for what the numbers mean and how to read them. ## Agents in the catalog The Agents Hub publishes these agents. Each one shows its category in the catalog, and you can filter on that category to narrow the list. For how each agent installs into a host, see the [Agent Kit](/secure-ai-coding/agent-kit). ## Availability Requires `endorctl` v1.7.1088 or later. Endor Labs authors and signs the catalog. The agents in the Agents Hub are designed to be implemented in your AI SDLC and workflows. You can view the agents available for implementation in the Agents Hub, but you can't yet add a custom agent inside Endor Labs. To see the available agents in more detail, and to learn how to create your own custom agent, see the open source [Endor Labs Agent Kit](https://github.com/endorlabs/endor-labs-agent-kit). ## Explore the Agents Hub Find an agent in the catalog, read what it does, and install it in your AI coding assistant. Read the usage metrics the Agents Hub reports for each agent in your tenant. See how an agent reaches Endor Labs data under a short-lived, read-only token attributed to you. Understand how Endor Labs signs the catalog and attributes every agent action to a person. # Trust and attribution Source: https://docs.endorlabs.com/secure-ai-coding/agents-hub/trust-and-attribution/index Beta
How Endor Labs signs the agent catalog and attributes every agent action to a person. Endor Labs built the Agents Hub so you can trust what an agent is and what it can do. Two properties support that. Endor Labs authors and signs the catalog, and every agent action carries the identity of the person the agent acts for and stays read-only. ## A signed, Endor-authored catalog Endor Labs authors the agents in the open source [endorlabs/endor-labs-agent-kit](https://github.com/endorlabs/endor-labs-agent-kit) repository and publishes them as a cryptographically signed release. Endor Labs verifies that signature against a pinned key before serving the catalog to your tenant. If verification fails, Endor Labs keeps serving the last known good catalog and never serves an unverified one. Because Endor Labs verifies the catalog on its side, the Agents Hub only ever shows you agents that came from the published, signed release. You can't add a custom agent to the Agents Hub in this release, and no third party can inject one. See the [safety model](/secure-ai-coding/agent-kit/safety-model) for how checksum verification protects an agent's files after you install it. ## Read-only by design Agents reach Endor Labs data under a read-only credential. An agent can read findings, projects, and other resources, but it can't change Endor Labs state. When an agent proposes a change, such as a dependency upgrade, it opens a pull request or merge request in your source control provider, and you review it there. The agent doesn't write the change back to Endor Labs. This keeps you in control of anything that lands. ## Attributed to a person Endor Labs attributes every request an agent makes to the person the agent acts for, and groups every request made under the same delegated token into one session. A session lasts as long as the token, up to one hour. Endor Labs sets attribution when it issues the credential, from the identity that authenticated. An agent can't assert that it's acting for someone else. Attribution means you can tell, per agent and per session, whose access an agent used and what it read. See [Agent activity](/secure-ai-coding/agents-hub/activity) for where this appears. # AI model findings Source: https://docs.endorlabs.com/secure-ai-coding/ai-model-discovery/ai-model-findings/index Find and manage priority issues related to AI models. Endor Labs can detect AI models and list them as dependencies when you run a scan with the `--ai-models` flag. You can view the detected AI models in the **Inventory** > **AI Models** section of the [Endor Labs user interface](#view-ai-models-in-your-namespace). You can define custom policies to flag the usage of specific AI providers, specific AI models, or models with low scores so that their usage raises findings as part of your scan. Endor Labs provides [AI model policy templates](/secure-ai-coding/ai-model-discovery/ai-model-policies) that you can use to create finding policies that are tailored to your organization's needs. You can [view these findings](#view-ai-model-findings-in-your-namespace) in **Code Dependencies** > **AI Models** on the **Findings** page. Run the following command to detect AI models in your repository. ```bash theme={null} endorctl scan --ai-models ``` When you run a scan with the `--ai-models` option, Endor Labs downloads Opengrep and runs Opengrep to detect AI models. Endor Labs detects AI models using pattern matching and can use LLM processing to improve detection accuracy. LLM processing is disabled by default. See [Supported AI model providers](#ai-model-detection) for the list of external AI models detected by Endor Labs. Only Hugging Face models are scored, as they are open source and provide extensive public metadata. Models from all other providers are detected but not scored due to limited metadata. ## Enable LLM processing for AI model detection To enable LLM processing in Endor Labs: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **System settings** > **Data privacy**. 3. Turn on **Code Segment Embeddings and LLM Processing**. See [Configure system settings](/platform-administration/configure-system-settings) for more information. **Privacy** When you enable LLM processing, Endor Labs uses a private and isolated Azure OpenAI Service deployment, which is not accessible from the public Internet and cannot be used for LLM training. To generate AI model findings: 1. Configure [finding policy](/secure-ai-coding/ai-model-discovery/ai-model-policies) to detect AI models with low scores and enforce organizational restrictions on specific AI models or model providers. 2. [View AI Model findings](#view-ai-model-findings-in-your-namespace). 3. To disable AI model discovery, set `ENDOR_SCAN_AI_MODELS=false` in your [scan profile](/scan/scan-profiles/configure-scanprofile-ui#configure-general-scan-profile-settings). ## AI model detection The following table lists the AI model providers currently supported by Endor Labs for model detection. For each provider, the table includes supported programming languages, if model scoring is available, and a reference link to the provider's API documentation. ## AI model discovery through monitoring scans By default, AI models are discovered during SCA scans run through GitHub App, Bitbucket App, Azure DevOps App, and GitLab App. You can view the reported AI models under **Inventory** > **AI Models** in the left sidebar. To disable AI model discovery, set `ENDOR_SCAN_AI_MODELS=false` as an additional environment variable in the [scan profile](/scan/scan-profiles/configure-scanprofile-ui#configure-general-scan-profile-settings) and assign the scan profile to the project. ## Detect AI models Configure finding policies and perform an endorctl scan to detect AI models in your repositories and review the findings. 1. Configure [finding policy](/secure-ai-coding/ai-model-discovery/ai-model-policies) to detect AI models with low scores and enforce organizational restrictions on specific AI models or model providers. 2. Run an endorctl scan with the following command. ```bash theme={null} endorctl scan --ai-models --dependencies ``` ## View AI models in your namespace To view all AI models that are used in your namespace: 1. Select **Inventory** > **AI Models** from the left sidebar. AI Models under Inventory 2. Use the search bar to look for any specific models. 3. Select a model, and click to see its details. 4. You can also navigate to **Findings** > **AI Models** from the left sidebar to view AI model findings. AI model findings ## View AI models in a project To view AI models that are used in a specific project: 1. Select **Projects** from the left sidebar and select a project. 2. Select **Inventory** and click **AI Models** under **Dependencies** to view findings. AI model dependencies # AI model policies Source: https://docs.endorlabs.com/secure-ai-coding/ai-model-discovery/ai-model-policies/index Learn about the predefined finding policy templates for CI/CD tools used in your software development environment. ## Policy templates for AI models Endor Labs provides the following finding policy templates for detecting AI models that have low Endor score. See [Finding Policies](/secure-ai-coding/ai-model-discovery/ai-model-policies/..) for details on how to create policies from policy templates. # AI Model Discovery Source: https://docs.endorlabs.com/secure-ai-coding/ai-model-discovery/index Discover and evaluate AI models with comprehensive scoring for security and operational risk. An AI model is a computational system designed to simulate human intelligence by performing tasks such as recognizing patterns, making decisions, predicting outcomes, or generating content. Many open source AI models are freely available for use, modification, and distribution. Just like dependencies, these AI models can bring operational and security risks in the organization that uses them. Gaining visibility into these risks can minimize the vulnerabilities introduced by them. Endor Labs picks the top ten thousand open source AI models available on Hugging Face and assigns Endor scores to them, so that you can make informed decisions before using them in your organization. You can search for AI models in the following ways: * **View detected AI models**: Select **Inventory** > **AI Models** from the left sidebar to see AI models discovered in your namespace. * **Search AI models from Hugging Face**: Select **Discovery** > **AI Models** from the left sidebar to search and evaluate models. * Type in the search bar and click **Search AI Models**. View AI models * Select a result to view details such as security, activity, popularity, and operational risk score. View AI model details * Click **Go to Hugging Face to see more** to open the model on the Hugging Face website. ## Understand the scores Each model carries an Endor score across four categories. Expand a category to see the factors that feed into it. The popularity score reflects the model's adoption and recognition within the AI community. Higher scores indicate greater usage and community engagement. * **Number of downloads**: More downloads indicate widespread adoption. * **Number of likes**: More likes suggest a positive reception from users. * **Published papers**: Models with linked academic papers receive higher credibility. * **GitHub repository**: Models with an associated GitHub repository score higher. * **Number of spaces using the model**: More integrations suggest broader utility. Models with many downloads, likes, citations, and integrations score higher. Models with fewer engagements score lower. The activity score measures how actively a model is discussed and maintained. * **Discussion posts**: Active community discussions contribute positively. * **Pull requests**: Indicates ongoing maintenance and improvements. Models with frequent discussions and active pull requests score higher. Models with limited activity receive lower scores. The operational score assesses the model's reliability, transparency, and usability. * **Reputable provider**: Models from well-known sources score higher. * **Model age**: Older, well-maintained models may score higher, but outdated models may receive penalties. * **Authorization requirements**: Restricted-access models score lower for accessibility but may gain points for security. * **Gated models**: If a model requires special access, it may impact usability. * **License information**: Models with clear licensing receive higher scores. * **License type**: Open licenses (permissive, unencumbered) generally score higher than restrictive ones. The following metadata factors are also considered. * **Metric information**: Essential for model evaluation. * **Dataset information**: Transparency about training data boosts the score. * **Base model information**: Important for derivative works. * **Training data, fine-tuning, and alignment training information**: Increases credibility. * **Evaluation results**: Demonstrates model performance. Models with comprehensive metadata, reputable providers, and clear licensing score higher. Models with unclear ownership, restrictive access, or missing details score lower. The security score evaluates potential risks associated with a model's implementation and distribution. * **Use of safe tensors**: Secure tensor formats boost the safety score. * **Use of potentially unsafe files**: Formats such as pickle, PyTorch, and Python code files pose security risks. * **Typosquatting risks**: Models that could be impersonating popular models receive lower scores. * **Example code availability**: Models that contain example code or code snippets can introduce potential issues and hence receive lower scores. Models that follow best security practices such as safe tensors, clear documentation, or vetted repositories score higher. Models receive lower scores if they use potentially unsafe formats such as pickle (`.pkl`) and unverified PyTorch (`.pth`) or show signs of typosquatting. For how the categories combine into a final score, see [AI model scores](/secure-ai-coding/ai-model-scores). # AI model scores Source: https://docs.endorlabs.com/secure-ai-coding/ai-model-scores/index Understand how AI Models are scored in Endor Labs. To evaluate AI models effectively, we use a multifactor scoring system that assesses popularity, activity, operational integrity, and security. Each model is assigned a composite score based on the following criteria. Expand each category to see its contributing factors. The popularity score reflects the model's adoption and recognition within the AI community. Higher scores indicate greater usage and community engagement. * **Number of downloads**: More downloads indicate widespread adoption. * **Number of likes**: More likes suggest a positive reception from users. * **Published papers**: Models with linked academic papers receive higher credibility. * **GitHub repository**: Models with an associated GitHub repository score higher. * **Number of spaces using the model**: More integrations suggest broader utility. Models with many downloads, likes, citations, and integrations score higher. Models with fewer engagements score lower. The activity score measures how actively a model is discussed and maintained. * **Discussion posts**: Active community discussions contribute positively. * **Pull requests**: Indicates ongoing maintenance and improvements. Models with frequent discussions and active pull requests score higher. Models with limited activity receive lower scores. The operational score assesses the model's reliability, transparency, and usability. * **Reputable provider**: Models from well-known sources score higher. * **Model age**: Older, well-maintained models may score higher, but outdated models may receive penalties. * **Authorization requirements**: Restricted-access models score lower for accessibility but may gain points for security. * **Gated models**: If a model requires special access, it may impact usability. * **License information**: Models with clear licensing receive higher scores. * **License type**: Open licenses (permissive, unencumbered) generally score higher than restrictive ones. The following metadata factors are also considered. * **Metric information**: Essential for model evaluation. * **Dataset information**: Transparency about training data boosts the score. * **Base model information**: Important for derivative works. * **Training data, fine-tuning, and alignment training information**: Increases credibility. * **Evaluation results**: Demonstrates model performance. Models with comprehensive metadata, reputable providers, and clear licensing score higher. Models with unclear ownership, restrictive access, or missing details score lower. The security score evaluates potential risks associated with a model's implementation and distribution. * **Use of safe tensors**: Secure tensor formats boost the safety score. * **Use of potentially unsafe files**: Formats such as pickle, PyTorch, and Python code files pose security risks. * **Typosquatting risks**: Models that could be impersonating popular models receive lower scores. * **Example code availability**: Models that contain example code or code snippets can introduce potential issues and hence receive lower scores. Models that follow best security practices such as safe tensors, clear documentation, or vetted repositories score higher. Models receive lower scores if they use potentially unsafe formats such as pickle (`.pkl`) and unverified PyTorch (`.pth`) or show signs of typosquatting. ## Final score calculation Each category contributes to the overall model score. The final score is a weighted sum of these factors, with weights adjusted based on real-world relevance and risk impact. Higher scores indicate well-documented, popular, actively maintained, and secure models, while lower scores highlight potential risks or lack of transparency. This scoring system enables users to make informed decisions when selecting AI models for their projects. Endor Labs continuously refines and expands its evaluation criteria; this document represents the current methodology snapshot. # Prerequisites for AI security code review Source: https://docs.endorlabs.com/secure-ai-coding/ai-security-review/ai-security-prerequisites/index Verify the prerequisites for AI security review Before you set up AI security code review, ensure that the following prerequisites are in place: * An active Endor Labs subscription with Endor Code Pro license. * Administrator access to your GitHub organization. * Access to configure scan profiles and policies. * Enable Code Segment Embeddings and LLM Processing in Data Privacy settings. ### Enable Code Segment Embeddings and LLM Processing Perform the following steps to enable code segment embeddings and LLM processing: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **SYSTEM SETTINGS** > **Data Privacy**. Enable Code Segment Embeddings and LLM Processing 3. Select **Code Segment Embeddings and LLM Processing**. 4. Click **Save Data Privacy Settings**. ### Verify license and feature access Perform the following steps to verify your license and feature access: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **License**. 3. Verify that you have **Security Review** in **Products** and **Features**. # Set up AI security code review with endorctl Source: https://docs.endorlabs.com/secure-ai-coding/ai-security-review/ai-security-review-endorctl/index Use endorctl to run AI security code review with GitHub environment variables. You can use AI security code review with endorctl and GitHub environment variables without requiring the GitHub App. This approach allows you to integrate AI security code review into your local development workflows. You can use this approach only if you have GitHub as your source control management system. Complete the following tasks to set up AI security code review with endorctl: * [Complete the prerequisites to use AI security code review with endorctl.](#prerequisites-to-use-ai-security-code-review-with-endorctl) * [Set up the environment variables required to run endorctl for AI security code review.](#set-up-environment-variables) * [Install and authenticate endorctl, build your project, and run a scan.](/introduction/getting-started) Scanning the repository creates the project in Endor Labs that you can use to configure the scan profile. * Configure a [scan profile](/secure-ai-coding/ai-security-review/ai-security-review-settings#configure-scan-profile-for-ai-security-code-review) for AI security code review. * Enable the [security review finding policy](/secure-ai-coding/ai-security-review/ai-security-review-settings#enable-finding-policy-for-ai-security-code-review). * Configure an [action policy](/secure-ai-coding/ai-security-review/ai-security-review-settings#configure-action-policy-for-pull-request-comments) if you want to get comments on your GitHub pull request with the details of the AI security code review. * [Run scans for AI security code review.](#pull-request-scan-with-ai-security-code-review) * [View results of the AI security code review.](/secure-ai-coding/ai-security-review/ai-security-review-results) ## Prerequisites to use AI security code review with endorctl Ensure that the following prerequisites are met before using AI security code review with endorctl: * An active Endor Labs subscription with Endor Code Pro license. * Access to configure scan profiles and policies * Code Segment Embeddings and LLM Processing enabled in Data Privacy settings * A GitHub token with appropriate permissions. ### Enable Code Segment Embeddings and LLM Processing Perform the following steps to enable code segment embeddings and LLM processing: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **SYSTEM SETTINGS** > **Data Privacy**. Enable Code Segment Embeddings and LLM Processing 3. Select **Code Segment Embeddings and LLM Processing**. 4. Click **Save Data Privacy Settings**. ### Verify license and feature access Perform the following steps to verify your license and feature access: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **License**. 3. Verify that you have **Security Review** in **Products** and **Features**. ## Set up environment variables Configure the following environment variables for GitHub integration: ```bash theme={null} # Required: SCM token with repo access export ENDOR_SCAN_SCM_TOKEN= # Required: Endor Labs authentication export ENDOR_API_CREDENTIALS_KEY= export ENDOR_API_CREDENTIALS_SECRET= export ENDOR_NAMESPACE= ``` ## Pull request scan with AI security code review To scan a pull request with AI security code review, fetch the pull request branch locally and checkout the branch. ```shell theme={null} git fetch origin pull//head:pr- git checkout pr- ``` For example, to scan pull request 12, you need to run the following commands. ```shell theme={null} git fetch origin pull/12/head:pr-12 git checkout pr-12 ``` After you have fetched and checked out the pull request branch, you can run the following command to scan the pull request with AI security code review. ```shell theme={null} endorctl scan \ -n \ --pr \ --security-review \ --scm-pr-id \ --scm-token $ENDOR_SCAN_SCM_TOKEN \ --enable-pr-comments ``` The following table describes the flags used in the command. # PR Comments for AI security code review Source: https://docs.endorlabs.com/secure-ai-coding/ai-security-review/ai-security-review-pr-comments/index Learn how AI security code review PR comments work and how to interpret them as a developer AI security code review PR comments provide automated feedback directly in your GitHub pull requests when potential security issues are detected in your code changes. This feature helps developers identify and fix security vulnerabilities before code is merged into the main branch. When you create or update a pull request, Endor Labs automatically scans the diff of the pull request. The scan data is sent to a private and secure AI model for security analysis. A comment is automatically posted to your PR with the analysis. You can review the findings and make necessary changes. If no security issues are detected, you can see a comment indicating a clean security review. ## Benefits of AI security code review PR comments You can get the following benefits with AI security code review PR comments: * Get security feedback without leaving your development workflow * Identify issues before code review or merge * Reduce the time between writing code and discovering security problems * Receive specific recommendations for fixing security issues * Understand the security implications of your code changes * Learn about security best practices through real examples ## Content of AI security code review PR comment After the analysis is complete, Endor Labs posts a comment directly on your pull request with the following information: * **Summary**: A summary of the code changes in the pull request along with the file name and location of the code changes. * **Security Changes**: A list of security changes in the pull request along with the file names and location of the security changes. The following example shows how an AI security code review PR comment appears in a GitHub pull request. Example of AI security review ### Summary of code changes The AI security review provides a comprehensive summary of all code changes in your pull request. The summary includes the following information: * **Detailed change analysis**: What was modified, added, or removed in each file. * **File paths and line numbers**: Exact locations of all changes. * **Technical implementation details**: Specific functions, configurations, and changes made in the code. * **Impact assessment**: Analysis of how changes affect the overall system. The following example shows a summary of code changes for a pull request. AI security code review PR comment summary ### Security Changes The AI security review analyzes your code changes across different security aspects and provides detailed findings for any security-relevant changes. The following sections describe the security changes in more detail. * [Comment structure of security changes](#comment-structure-of-security-changes) * [Severity levels](#severity-levels) * [Category icons for security changes](#category-icons-for-security-changes) The following example shows a security changes for a pull request. AI security code review PR comment security changes #### Comment structure of security changes The comment structure is as follows: * **Security Changes Header**: Numbered count of security changes found. * **Security Aspect Icons**: Visual indicators and category icons for quick identification. * **Severity Level**: Critical, High, Medium, or Low classification. * **Detailed Description**: Comprehensive explanation of the security concern. * **Code References**: Specific file paths and line numbers with clickable links. * **Justification Section**: Detailed explanation of why the change poses a security risk. #### Severity levels The following severity levels are used to classify the security changes: * **🔴 Critical**: Immediate security threats (prompt injection vulnerabilities, authentication bypasses). * **🟠 High**: Significant security risks (API endpoint issues, access control problems). * **🟡 Medium**: Security concerns to address (PII data handling, dependency security, JWT implementation). * **🟢 Low**: Minor security issues or best practice violations. #### Category icons for security changes The following category icons are used to classify the security changes: * **📦 Dependency**: Dependency security, library vulnerabilities. * **🤖 AI**: AI model security, prompt injection risks. * **🔒 Access Control**: Authentication, authorization, session management. * **🔌 API Endpoint**: API security controls, rate limiting. * **🗄️ Database**: Query construction, data access controls. * **🔐 Cryptographic**: Encryption, hashing, key management, JWT implementation. * **💳 Payment Processing**: Financial data security, PCI compliance. * **🧠 Memory Protection**: Buffer overflows, memory leaks. * **👤 PII Data Handling**: PII handling, data classification, local storage security. * **📝 Input Validation**: Data sanitization, injection prevention. * **🏗️ Infrastructure**: Cloud resources, container security. * **🚀 CI/CD**: Build pipeline security, artifact integrity. * **⚙️ Configuration**: Secrets management, environment variables. * **🌐 Network**: Firewall rules, network segmentation. # View AI security code review results Source: https://docs.endorlabs.com/secure-ai-coding/ai-security-review/ai-security-review-results/index Learn how to view the AI security code review results. You can view the AI security code review results in the Endor Labs UI. You can also enable PR comments to get a comment on your GitHub PR with the details of the AI security code review. If you use merge queues, Endor Labs provides security review for the PRs until they are added to the merge queue. Endor Labs does a final security review on the merged commit SHA to the default branch. ## View AI security code review results To view the AI security code review results in Endor Labs application: 1. Select **Projects** from the left sidebar. 2. Select the project for which you want to view the AI security code review results. 3. Select **Security Review**. Security Review You can view the AI security code review results for all the pull requests raised in the project. You can also search for a specific pull request and view the results. 4. You can filter the results by the type of the security issues, the severity of the security issues, the author of the PR, the approvers, and the creation time of the PR. You can select **Advanced** to enter a search query to filter the results. For example, you can filter the results to show only the critical security issues that are part of unmerged pull requests: `(spec.level in ["SECURITY_REVIEW_LEVEL_CRITICAL"] and spec.repository_pull_request_spec.merged != true)` 5. Click on a pull request to view the detailed security analysis of the PR and the list of security risks along with their severities. You can click links against the security analysis to go directly to the lines of code that has the security risk. You can also click the links to view the pull request and the specific commit that introduced the security risk. Security Review Report 6. Select the arrow next to a security risk to view the details of the security risk. You can view the analysis of the security risk, the code snippet associated with the risk, and the details of the pull request. Security Risk Details ## Security review GitHub pull request comment If you configure the action policy to get comments on your GitHub pull requests, Endor Labs comments on the pull request with the security analysis. Security Review GitHub pull request comment # Set up AI security code review with GitHub App Source: https://docs.endorlabs.com/secure-ai-coding/ai-security-review/ai-security-review-settings/index Learn how to set up and configure AI security code review for your projects To set up AI security code review, you need to complete the following tasks: * Ensure that the [GitHub App](#github-app-configuration) is installed and configured properly. If you are using endorctl, skip this step and ensure that you have set up the [environment variables](/secure-ai-coding/ai-security-review/ai-security-review-endorctl) required for the endorctl scan command. * Configure a [scan profile](#configure-scan-profile-for-ai-security-code-review) for AI security code review. * Enable the [security review finding policy](#enable-finding-policy-for-ai-security-code-review). * Configure an [action policy](#configure-action-policy-for-pull-request-comments) if you want to get comments on your GitHub pull request with the details of the AI security code review. ## GitHub App Configuration Install the GitHub App if you don't have it already. See [GitHub App](/setup-deployment/scm-integrations/github-app) for more information. Ensure that you enable the following settings: * **Pull Request Scans:** **Pull Request Scans** allows Endor Labs to scan the pull requests. You must enable this setting so that AI security code review can proceed for a pull request. * **Pull Request Comments:** **Pull Request Comments** allows Endor Labs to comment on a pull request in GitHub. This setting is optional, and you need to enable this setting if you want a comment on your GitHub pull request with the details of the AI security code review. In addition, you also need to select **Pull Request Comments** in your scan profile and set up an action policy. ## Configure scan profile for AI security code review Create a [scan profile](/scan/scan-profiles/build-tools) for AI security code review and configure the following options: * **Pull Request Scans**: Mandatory. This setting allows Endor Labs to scan the pull requests. * **Pull Request Comments**: Optional. This setting allows Endor Labs to comment on a pull request in GitHub. * **AI security code review Scans**: Mandatory. This setting allows Endor Labs to scan the pull requests for AI security code review. * **Disable Code Summary**: Optional. This setting allows you to disable the code summary for the AI security code review. * **Custom Prompt**: Optional. You can enter a custom prompt to modify how AI security code review detects and categorizes security-related changes. Scan profile for AI security code review After you create the scan profile, assign the scan profile to the projects for which you want to set up AI security code review. ## Enable finding policy for AI security code review Ensure that the Security Review policy is enabled under finding policies. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Finding Policies**. 3. Search for `Security Review` and ensure that the policy is enabled. Enable finding policy for AI security code review ## Configure action policy for pull request comments If you want to get comments on your GitHub pull requests, you need to set up an action policy. 1. Select **User menu** > **Policies & Rules** from the left sidebar. 2. Select **Action Policies**. 3. Click **Create Action Policy**. 4. Select **Security Review** as the **Policy Template**. 5. Choose the severity threshold to trigger the AI security code review. You can choose from the following severity thresholds: * **Any** * **Low** * **Medium** * **High** * **Critical** 6. Select **Pull Request** as the **Branch Type**. 7. Choose **Enforce Policy** as the action, and select **Warn or Break the Build** depending on your preference. 8. Configure include and exclude patterns for the policy. 9. Name the policy and provide a description. 10. Enter tags if required for the policy. 11. Click **Create Action Policy** to save the policy. See [Action Policies](/platform-administration/policies/action-policies) for more information on setting up an action policy. Configure action policy for PR comments # AI Security Review Source: https://docs.endorlabs.com/secure-ai-coding/ai-security-review/index Identify potential security issues in your pull requests using AI-powered review. AI security code review provides automated code review capabilities using artificial intelligence to identify potential security issues in your codebase. **Availability** AI security code review is available only for GitHub. You can set up AI security code review through the [Endor Labs GitHub App](/secure-ai-coding/ai-security-review/ai-security-review-settings) or using [endorctl](/secure-ai-coding/ai-security-review/ai-security-review-endorctl). After you set up AI security code review, creating a pull request triggers an Endor Labs scan on the diff. Endor Labs sends the scan data to an AI model to produce a security analysis and generates a report. You can view the report in the Endor Labs user interface. You can also enable pull request comments to get a comment on your GitHub pull request with the details of the AI security code review. The following sections provide information on how to set up AI security code review, customize a scan profile, and view the AI security code review results. Verify the prerequisites for AI security code review. Learn how to set up AI security code review with GitHub App. Learn how to view the AI security code review results. Learn how AI security code review PR comments work and how to interpret them. Learn how to view AI security code review dashboard. Use endorctl and GitHub environment variables for AI security code review. # Hugging Face organization models Source: https://docs.endorlabs.com/secure-ai-coding/huggingface-organization/index Connect a Hugging Face organization to Endor Labs to scan and score all its AI models. Endor Labs provides a Hugging Face integration that continuously scans all models in your Hugging Face organization and scores them for security, activity, popularity, and quality. You can use the integration to gain visibility into both public and private models, identify risks, and govern AI model usage across your organization. The scans discover models across the organization and surface them in your inventory along with their Endor scores. Providing a Hugging Face access token extends coverage to private and gated models in addition to public ones. Discovered models are also correlated with models referenced in your project source code, enabling previously undiscoverable private models to be identified and included in your inventory. Only users with the admin authorization role can create and manage installations. ## Configure the Hugging Face integration To connect a Hugging Face organization and scan its models: 1. Select **Projects** from the left sidebar. 2. Click **Add Project**. 3. Under **Namespace**, select the Endor Labs namespace for this installation. We recommend you use a [child namespace](/platform-administration/namespaces) for better organization of your projects. 4. Select **Hugging Face**. Add Hugging Face organization 5. Enter the host URL of your Hugging Face organization in the format `https://huggingface.co/`, for example `https://huggingface.co/meta-llama`. 6. Optionally, enter your Hugging Face access token. A token with read-only access is required to scan private models. 7. Click **Create**. Endor Labs scans all models in the organization and reports findings. ## Scan with endorctl You can scan a Hugging Face organization from the command line using the following command: ```bash theme={null} endorctl sync-org --namespace --platform-source=huggingface --name= ``` Replace `` with the organization name as it appears in Hugging Face, for example `meta-llama` or `google`. Alternatively, you can provide the installation UUID instead of the organization name: ```bash theme={null} endorctl sync-org --namespace --platform-source=huggingface --uuid= ``` # Manage Hugging Face integrations on Endor Labs Source: https://docs.endorlabs.com/secure-ai-coding/huggingface-organization/manage-huggingface/index Learn how to manage your Hugging Face integrations in Endor Labs. You can make changes to the Hugging Face integrations or delete them. You can view the activity logs for the Hugging Face integration and rescan your organizations on demand. 1. Select **User menu** > **Integrations** from the left sidebar. 2. Select **Hugging Face**. 3. Select the vertical three dots next to the integration. You can choose from the following options: * [**Update Credentials**](#update-credentials) * [**View Sync Logs**](#view-sync-logs) * [**Delete Integration**](#delete-a-hugging-face-integration) ### Update credentials 1. Select the vertical three dots next to the integration, and select **Update Credentials**. You cannot update the host URL of an existing integration. To monitor a different organization, create a new integration. 2. Enter your new **Access Token**. 3. Select **Save**. **Initiate rescan manually** Credential updates take effect at the next scheduled scan cycle. To apply changes immediately, select **Rescan Org**. ### Delete a Hugging Face integration To delete a Hugging Face integration, select the vertical three dots next to the integration, and select **Delete Integration**. Deleting the integration removes all models and associated data discovered through that organization from your namespace. ### View sync logs Endor Labs detects and reports installation and synchronization errors during organization sync. These include expired tokens, insufficient permissions, invalid host configurations, and certificate issues. Sync logs report those errors that you can resolve. To view sync logs, click the three vertical dots next to the integration, and select **View Sync Logs**. The sync logs display details of synchronization attempts, including timestamps, error types, and diagnostic messages. These logs help identify issues such as authentication failures or configuration problems. #### Types of errors The sync logs detect and display the following categories of sync failures: * **Expired or invalid Personal Access Tokens (PATs)**: The PAT used for authentication has expired or is no longer valid. Edit the integration and provide a valid token. * **Insufficient PAT permissions**: The PAT does not have the required scopes, such as repository read access. You must generate and provide a PAT with the correct access. * **Certificate related access issues**: The certificates required to connect to the SCM are invalid, outdated, or untrusted. This error occurs in self-hosted GitLab instances that use custom SSL certificates. Update the certificate configuration or ensure the certificate chain is properly trusted to resolve the issue. * **Incorrect or invalid host URLs**: The configured URL is incorrect or unreachable. Since you cannot edit the host URL, you need to delete and reinstall the integration using the correct URL. After you resolve the issue, the error is automatically cleared during the next successful scan. You can manually re-trigger the scan using **Rescan Org** to verify the resolution immediately. ### Rescan an organization Select **Rescan Org** next to an integration to manually trigger a scan outside the scheduled cycle. ### Add another organization To connect an additional Hugging Face organization to the same namespace: 1. Select **Add Organization**. 2. Enter the **Host URL** for the organization, for example `https://huggingface.co/meta-llama`. 3. Optionally, enter an **Access Token**. A token with read-only access is required to scan private models. Add Hugging Face integration 4. Select **Create**. # View Hugging Face organization models Source: https://docs.endorlabs.com/secure-ai-coding/huggingface-organization/view-models/index View, filter, and explore AI models discovered in your Hugging Face organization. After a scan runs, Endor Labs groups discovered models by organization and scores each one for security, activity, popularity, and quality. You can explore models across all connected organizations, inspect individual model metadata, and use filters to identify models that need attention. 1. Select **Inventory** from the left sidebar. 2. Select **HuggingFace Orgs**. 3. You can view a list of models including their organization name, URL, and total model count. Hugging Face organizations UI 4. Select a model row to view the model details. The model details include the following information: * **Model**: The model name in `author/model-name` format. * **Visibility**: Whether the model is public or private. * **License**: The model's declared license. * **Scores**: Endor scores for security, activity, popularity, and quality. See [AI model scores](/secure-ai-coding/ai-model-scores) to learn how Endor Labs calculates each score. Hugging Face model details 5. Select a model to open the detail drawer. The drawer has two tabs: * **Overview**: Shows model metadata including URL, license, author, created and last modified dates, authentication requirements, gated status, downloads, likes, spaces using the model, tags, datasets, model lineage, and importing projects. Hugging Face model overview * **OSS Scores**: Shows the overall Endor score out of 10, broken down by Security, Activity, Popularity, and Operational scores, along with the individual score factors. Hugging Face model scores 6. Click on **View details** to open the model details in a new tab. Hugging Face view details ## Filter and search models The filter bar at the top of the **HuggingFace Orgs** applies across all Hugging Face organizations and their models. Enter a term in the **Search models by name** field to filter models by name across all organizations. Organization rows with no matching models are hidden during search. Use the following filters to narrow results: * **Visibility**: Filter by public or private access status. Select one or more visibility options from the dropdown. * **Task**: Filter by the pipeline task associated with the model, such as `text-generation` or `image-classification`. Select one or more tasks from the dropdown. * **Framework**: Filter by the ML framework associated with the model, such as PyTorch or TensorFlow. Select one or more frameworks from the dropdown. * **License**: Filter by the model's declared license, such as MIT or Apache 2.0. Select one or more licenses from the dropdown. Select **Clear Filters** to remove all active filters. # Secure AI Coding Source: https://docs.endorlabs.com/secure-ai-coding/index Secure your AI-powered development workflows and govern AI model usage. AI models and machine learning components have become integral parts of modern software development. Just like traditional dependencies, these AI models can introduce operational and security risks to your organization. Endor Labs provides comprehensive capabilities to help you gain visibility into AI model risks and make informed decisions about AI model usage. Install ready-to-use Endor Labs security agents in your AI coding assistant. Browse the agent catalog and monitor how your team uses each agent. Identify potential security issues in your pull requests and get recommendations to fix them. Discover open-source components and troubleshoot errors with intelligent recommendations. Discover and evaluate AI models from Hugging Face with comprehensive scoring. Understand how AI models are scored across security, activity, popularity, and operational integrity. Scan and inventory all models in a Hugging Face organization, including private models. # CI/CD Integration Source: https://docs.endorlabs.com/setup-deployment/ci-cd/index Integrate Endor Labs scanning into your CI/CD pipelines. CI Scans are used to focus team's attention and establish development workflows on the most actionable issues, prioritizing the development team's time. CI Scans can be triggered directly from automated CI/CD pipelines, looking for new vulnerabilities relative to the baseline established for the target branch. These CI Scans provide immediate feedback to developers in the form of PR comments and can also enforce policies to break builds, block PRs, send notifications, open tickets, and more. CI scans are the most actionable method to prevent vulnerabilities from entering your repositories. Git must be installed and available where `endorctl scan` runs. If your pipeline does not include it, install it in your job or use a runner image that provides it. Refer to [Git documentation](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) for installation instructions. Perform CI scans using: * [endorctl CLI](/developers-api/cli) * [Scan with GitLab pipeline](/setup-deployment/ci-cd/scan-with-gitlab) * [Scan with GitHub Actions](/setup-deployment/ci-cd/scan-with-github-actions) * [Scan with Circle CI](/setup-deployment/ci-cd/scan-with-circleci) * [Scan with Jenkins](/setup-deployment/ci-cd/scan-with-jenkins) * [Scan with Azure DevOps](/setup-deployment/ci-cd/scan-with-azuredevops) * [Scan with Bitbucket](/setup-deployment/ci-cd/scan-with-bitbucket) * [Scan with Google Cloud Build](/setup-deployment/ci-cd/scan-with-google-cloud-build) * [Scan with Buildkite](/setup-deployment/ci-cd/scan-with-buildkite) See [scanning strategies](/scan/sca/scanning-strategies) to learn techniques for effectively scanning and monitoring different versions of your projects with Endor Labs. `endorctl` is a command line utility designed to bring the functionality of Endor Labs into your software delivery workflows. `endorctl` has multiple command flags to help you facilitate operational and security risk monitoring. Developers can integrate Endor Labs into Continuous Integration Workflows using the `endorctl scan`. * `endorctl scan` - You can use endorctl scan to monitor your projects using Endor Labs, and you can update the scan information each time to keep monitoring the project for new findings. The `endorctl scan` command will scan a specific version of your repository, such as the default branch, a tagged release version, or a commit SHA. * `endorctl scan --pr` - You can use the `endorctl scan --pr` command to scan a specific version of your source code for security and operational risks as part of your continuous integration workflows or CI runs. The `endorctl scan --pr` command performs a one-time evaluation of your project, focusing on security and operational risks, rather than providing continuous monitoring. CI runs are shown in the **Scan History** section of each project and are stored for three weeks so that you can analyze and review them on the Endor Labs user interface. See [PR scans](/scan/pr-scans) for more information. Any continuous integration workflows generally run using the `endorctl scan --pr` command unless a scan is run on a created tag release, a push to the default or specific branch, or a commit SHA that will be deployed to production. **Clone depth** For scans to succeed, configure shallow clone in your CI job to include the ref and commit you intend to scan. Set `ENDOR_SCAN_SHALLOW_CLONE=true` in your environment to use shallow clone when Endor Labs clones the repository. ### Authenticating in CI with Keyless Authentication Keyless Authentication enhances security and minimizes the expenses associated with secret rotation. Keyless authentication is Endor Labs recommended path to scan your projects in the CI workflows. See [Keyless Authentication](/setup-deployment/ci-cd/keyless-authentication) for more information. # Keyless authentication in AWS Source: https://docs.endorlabs.com/setup-deployment/ci-cd/keyless-authentication/aws-keyless-auth/index Learn how to implement keyless authentication for AWS. To enable keyless authentication in AWS you'll first need permissions to create or modify the following roles and an instance profile with the appropriate roles configured. 1. An instance access role - The instance access role is assigned to the compute resource, which needs to access Endor Labs. Your instance access role may already exist and you must ensure this role provides the permissions to allow the role to assume the role of a dedicated federation role. 2. A dedicated federation role - The dedicated federation role should have no permissions in AWS. Endor Labs will authorize requests that come from this role. Perform the following steps to configure keyless authentication in AWS. 1. [Create or modify](#create-or-select-an-instance-profile) an existing [Instance profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) to assign a role to your EC2 instance. 2. [Create or modify a role an instance access role, which enables services to assume a dedicated federation role.](#create-or-modify-an-instance-access-role) 3. [Assign this role to the instance profile.](#assign-instance-access-role-to-the-instance-profile) 4. [Create a dedicated federation role to provide access to Endor Labs, which will be assumed by the instance access role.](#create-a-dedicated-federation-role) 5. [Create an authorization policy in Endor Labs.](#create-an-authorization-policy-in-endor-labs) 6. [Test keyless authentication.](#test-keyless-authentication-with-aws) To configure keyless authentication with EKS, you will need an existing IAM ODIC provider for your cluster and to configure a Kubernetes service account annotated with your instance access role. You won't need to create or assign roles to instance profiles or create any instance profiles. See the [AWS Documentation](https://docs.aws.amazon.com/eks/latest/userguide/associate-service-account-role.html) for additional information. You will need to have the [AWS CLI installed](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to follow the following procedure. ### Create or select an instance profile An instance profile allows users to attach a single role to an EC2 instance. If you do not already have a pre-defined role or instance profile used by your EC2 instances you should create an instance profile for Endor Labs access. To create an instance profile using the AWS CLI: ```bash theme={null} aws iam create-instance-profile --instance-profile-name EndorLabsAccessProfile ``` ### Create or modify an instance access role To successfully authenticate to Endor Labs you will need to assign an instance access role to the instance profile you created above. The instance access role must at a minimum allow the compute resources that require access to perform the action `sts:AssumeRole`. If you already have a role you intend to assign to your instance profile, ensure that it has permissions to allow your compute resources to perform this action. If you do not have an existing role you intend to use, create the role named `endorlabs-instance-access-role` using the following instructions. Add the following json to a file called `endorlabs-instance-access-role.json` ```bash expandable theme={null} cat > endorlabs-instance-access-role.json < Your instance profile name and role name will need to be updated based on the names of these resources in your environment. ```bash theme={null} aws iam add-role-to-instance-profile --instance-profile-name EndorLabsAccessProfile --role-name endorlabs-instance-access-role ``` Finally, create your EC2 instance and [ensure that your instance profile is assigned to it](https://repost.aws/knowledge-center/attach-replace-ec2-instance-profile). ### Create a dedicated federation role A dedicated federation role is leveraged to provide a least privileged role that enables access to Endor Labs. This role is designed to be assumed only by specific other roles and does not provide access to AWS resources. To create your federation role you will need the name and AWS account number of the instance access role, which should look similar to the following policy json: ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::$ACCOUNT:role/$ROLE_NAME" }, "Action": "sts:AssumeRole" } ] } ``` First, get the account number of the role: ```bash theme={null} export ACCOUNT=$(aws sts get-caller-identity | jq -r '.Account') ``` Then define the name of the instance access role. For the following example, assume it is `endorlabs-instance-access-role`. ```bash theme={null} export ROLE_NAME=endorlabs-instance-access-role ``` Next, create the IAM policy document. ```bash theme={null} cat > endorlabs-federation-aws-role.json << EOF { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::${ACCOUNT}:role/${ROLE_NAME}" }, "Action": "sts:AssumeRole" } ] } EOF ``` Next, apply the policy document as a role: ```bash theme={null} aws iam create-role --role-name endorlabs-federation --assume-role-policy-document file://endorlabs-federation-aws-role.json ``` Finally, fetch the ARN of the IAM role you've created using the following command and create an authorization policy for it in Endor Labs. To fetch the ARN of the Endor Labs federation role use the following command: ```bash theme={null} aws iam list-roles | jq -r '.Roles[] | select(.Arn|contains("endorlabs-federation"))'.Arn ``` ### Create an authorization policy in Endor Labs Create an authorization policy in the Endor Labs user interface by following these steps: 1. Login to Endor Labs as an administrator. 2. Select **User menu** > **Settings** from the left sidebar. 3. Select **Access Control** > **Auth Policy** from the left sidebar. 4. Click **Add Auth Policy** 5. Under Identity Provider Select **AWS role** 6. Provide the appropriate permissions for your authorization policy. 7. Under claims use the Key **User** and the value of the ARN that you fetched in the previous command. 8. Click **Save Auth Policy** to finalize your keyless authentication setup. ### Test keyless authentication with AWS On the EC2 instance you've configured for keyless authentication, download and install the latest version of `endorctl`. See [our documentation for instructions on downloading the latest version](/developers-api/cli/install-and-configure) To scan with keyless authentication you must use the flag `--aws-role-arn=` for federated access to Endor Labs such as in the below example: ```bash theme={null} endorctl --aws-role-arn= api list -r Project -n --page-size=1 ``` You've set up and configured keyless authentication. Now you can run a test scan to ensure you can successfully scan projects using keyless authentication with AWS. # Keyless authentication for Azure Source: https://docs.endorlabs.com/setup-deployment/ci-cd/keyless-authentication/azure-keyless-auth/index Learn how to implement keyless authentication for Azure. To enable keyless authentication in Azure, you need to configure your Azure virtual machine with a managed identity and create an authorization policy in Endor Labs. Complete the following tasks to set up keyless authentication in Azure. 1. [Enable Azure Managed Identity for the virtual machine in the Azure Portal.](#enable-azure-managed-identity) 2. [Configure the Azure virtual machine.](#configure-the-azure-virtual-machine) 3. [Create an authorization policy in Endor Labs.](#create-an-authorization-policy-in-endor-labs) ## Enable Azure managed identity You must enable Azure Managed Identity for your virtual machine from the Azure portal. For more information, refer to [Azure managed identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-to-configure-managed-identities?pivots=qs-configure-portal-windows-vm). ## Configure the Azure virtual machine You need to configure the Azure virtual machine with endorctl and configure endorctl to use Azure Managed Identify. ### Verify the connection to the Azure virtual machine instance Log in to your Azure virtual machine and run the following command. ```sh theme={null} curl -s -H Metadata:true "http://169.254.169.254/metadata/instance?api-version=2021-02-01" ``` The command returns the metadata details of the virtual machine instance in the raw json format. ### Download endorctl on the virtual machine instance Download and install the latest version of endorctl in your virtual machine. See [endorctl](/developers-api/cli/install-and-configure) for the installation options available for endorctl. The following example shows how you can download the endorctl binary directly. ```bash theme={null} ## Download the latest CLI for Windows AMD64 curl -O https://api.endorlabs.com/download/latest/endorctl_windows_amd64.exe ## Check the expected checksum of the binary file curl https://api.endorlabs.com/sha/latest/endorctl_windows_amd64.exe ## Verify the expected checksum and the actual checksum of the binary match certutil -hashfile .\endorctl_windows_amd64.exe SHA256 ## Rename the binary file ren endorctl_windows_amd64.exe endorctl.exe ``` If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ### Set the environment variable Set the environment variable `ENDOR_AZURE_CREDENTIALS_MANAGED_IDENTITY_ENABLE` to true in your virtual machine instance. ```sh theme={null} export ENDOR_AZURE_CREDENTIALS_MANAGED_IDENTITY_ENABLE=true ``` Run the following command to check the status of the environment variable. ```sh theme={null} echo $ENDOR_AZURE_CREDENTIALS_MANAGED_IDENTITY_ENABLE ``` If the variable is set, then the command returns `true`. ## Create an authorization policy in Endor Labs Create an authorization policy for Azure in the Endor Labs user interface. See [set up authorization policy](/platform-administration/rbac/authorization-policies#set-up-authorization-policies) for more information on creation an authorization policy. Choose the following parameters when you create the authorization policy. * Select **Azure** as the **Identity Provider**. * Select **Code Scanner** in **Permissions**. * Enter values for the following claims: * Tenant ID: Identifies your Azure organization. * App ID: Identifies the application requesting access. * Object ID: Unique ID assigned to the virtual machine. * Subscriptions (optional): Azure subscriptions linked to the identity. * Select **Add permission rule** to define granular permissions by specifying the resource kinds and allowed methods. Azure authorization policy in Endor Labs ### Test keyless authentication Once the authorization policy is set up, you can test keyless authentication using endorctl. For example, run the following command to fetch the number of projects in a namespace with keyless authentication set up. ```sh theme={null} endorctl api list -r Project -n demo --enable-azure-managed-identity --count ``` The following example shows the response for the preceding command when keyless authentication is successful. ```json theme={null} { "count_response": { "count": 3 } } ``` You’ve set up and configured keyless authentication. Now you can run a test scan to ensure you can successfully scan projects using keyless authentication with Azure. # Keyless authentication in GitHub Source: https://docs.endorlabs.com/setup-deployment/ci-cd/keyless-authentication/github-keyless-auth/index Learn how to implement keyless authentication in GitHub. To enable Keyless Authentication for GitHub Actions, you'll need to perform the following steps: 1. Ensure you are using the Endor Labs [GitHub Action](https://github.com/endorlabs/github-action.git) in your GitHub workflow. 2. Edit your GitHub Action workflow to add permission settings for the GitHub `id-token` and `contents`. 3. Create an authorization policy for `GitHub Action OIDC`. 4. Test that you can successfully scan a project using `GitHub Action OIDC`. ### Add a GitHub Action OIDC authorization policy To ensure that the GitHub Action OIDC identity can successfully login to Endor Labs, create an authorization policy in Endor Labs. To create an authorization policy: 1. Select **User menu** > **Settings** from the left sidebar. 2. Select **Access Control** > **Auth Policy**. 3. Click **Add Auth Policy**. 4. Select **GitHub Action OIDC** as your identity provider. 5. Select the permission for the GitHub Action. This permission should be `Code Scanner`. 6. For the claim use the key `user` and put in a matching value that maps to the organization of your GitHub repository. ### Configure your GitHub Action workflow To configure your GitHub Action workflow with GitHub Action OIDC you can use the following example as a baseline. The important items in this workflow are: 1. The Usage of the Endor Labs GitHub Action. 2. Setting Job level permissions to allow writing to the GitHub `id-token` and reading repository `contents`. The examples pin the Endor Labs GitHub Action to release `v1.1.12`. To use a newer release, copy the **Use in your workflow** reference from **Latest GitHub Action Release** in [Secure GitHub Actions with immutable commit SHA](/setup-deployment/ci-cd/scan-with-github-actions#secure-github-actions-with-immutable-commit-sha). ```yaml expandable theme={null} name: Example Scan of OWASP Java on: workflow_dispatch jobs: create_project_owasp: permissions: id-token: write # This is required for requesting the JWT contents: read # This is required to checkout and read your repository code runs-on: ubuntu-latest steps: - name: Checkout Repo uses: actions/checkout@v3 with: repository: OWASP-Benchmark/BenchmarkJava - name: Setup Java uses: actions/setup-java@v3 with: distribution: 'microsoft' java-version: '17' - name: Compile Package run: mvn clean install - name: Scan with Endor Labs uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'demo' scan_summary_output_type: 'json' pr: false scan_secrets: true scan_dependencies: true ``` Now that you've successfully configured your GitHub Action workflow file you can use this workflow file or one of your own designs to run a test scan using Keyless authentication for GitHub Actions. # Keyless authentication in Google Cloud Source: https://docs.endorlabs.com/setup-deployment/ci-cd/keyless-authentication/google-keyless-auth/index Learn how to implement keyless authentication in Google Cloud. To enable Keyless Authentication in GCP you'll first need permissions to create service accounts and assign these accounts roles to GCP. The workflow to enable keyless authentication is: 1. Create a service account with no permissions for federation. 2. If you do not attach a service account to compute resources or use the default service account, we recommend creating a new service account for the compute resources. Create a service account to attach to compute resources and impersonate the federation service account. 3. Create an authorization policy to allow the federation service account to authenticate to Endor Labs. 4. Provision the compute resources with the appropriate permissions. 5. Test Keyless authentication. ### Create GCP service accounts and authorization policies To create your service accounts, first export your GCP project name as an environment variable: ```bash theme={null} export PROJECT= ``` Create a federation service account called `endorlabs-federation`: ```bash theme={null} gcloud iam service-accounts create endorlabs-federation --description="Endor Labs Keyless Federation Service Account" --display-name="Endor Labs Federation Service Account" ``` Create a keyless authentication service account to assign to compute resources called `endorlabs-compute-service`: ```bash theme={null} gcloud iam service-accounts create endorlabs-compute-service --description="Endor Labs Service account for keyless authentication" --display-name="Endor Labs Compute Instance SA" ``` This is needed if you don't already have service accounts for your compute resources. If you do, you need to modify the existing permissions to allow the existing service account to create a federation token. Assign the `serviceAccountOpenIdTokenCreator` role to the `endorlabs-compute-service` service account: ```bash theme={null} gcloud projects add-iam-policy-binding $PROJECT --member="serviceAccount:endorlabs-compute-service@$PROJECT.iam.gserviceaccount.com" --role="roles/iam.serviceAccountOpenIdTokenCreator" ``` Use the following command to create an authorization policy to allow the `endorlabs-federation` account to authenticate to your Endor Labs tenant. Replace `` with your Endor Labs tenant name and `` with your GCP project name. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ```bash expandable theme={null} endorctl api create -r AuthorizationPolicy -d '{ "tenant_meta": { "namespace": "" }, "meta": { "name": "Keyless Auth", "kind": "AuthorizationPolicy", "tags": ["gcp"] }, "spec": { "clause": ["email=endorlabs-federation@.iam.gserviceaccount.com", "gcp"], "target_namespaces": [""], "propagate": true, "permissions": { "rules": {}, "roles": [ "SYSTEM_ROLE_CODE_SCANNER" ] }, } }' ``` You've now set up the foundation of keyless authentication. You'll now need to provision your compute resources with the appropriate GCP scopes and service account. See [Provision and test keyless authentication for GKE workloads](#provision-and-test-keyless-authentication-for-gke-workloads) for instructions on setting up GKE for keyless authentication. See [Provision and Test Keyless Authentication for GCP Virtual Machine Instances](#provision-and-test-keyless-authentication-for-gcp-virtual-machine-instances) for instructions on setting up a virtual machine instance for keyless authentication. ### Provision and test keyless authentication for GKE workloads #### Prerequisites The following prerequisites are required to setup keyless authentication on GKE workloads: * Workload identity is enabled on the target GKE cluster. See the [GCP documentation on using workload identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) for instructions on migrating existing cluster node pools or creating new clusters to use GCP workload identity. * The gcloud auth plugin is installed and operational on your machine. See the [GCP instructions on enabling the gcloud auth plugin](https://cloud.google.com/blog/products/containers-kubernetes/kubectl-auth-changes-in-gke) for more details. * The kubectl CLI is installed. See [the Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/) for instructions. #### Procedure The following instructions require you to export these environment variables: ```bash theme={null} export PROJECT= export CLUSTER_NAME= ``` Optionally, create a GKE cluster with workload identity enabled if you do not already have one: ```bash theme={null} gcloud container clusters create keyless-test --workload-pool=endor-github.svc.id.goog --scopes https://www.googleapis.com/auth/cloud-platform ``` ```bash theme={null} gcloud container clusters get-credentials $CLUSTER_NAME ``` Optionally, create a dedicated namespace: ```bash theme={null} kubectl create namespace endorlabs ``` ```bash theme={null} kubectl create serviceaccount endorlabs-compute-service -n endorlabs ``` Replace `` with your GCP project name. ```bash theme={null} gcloud iam service-accounts add-iam-policy-binding endorlabs-compute-service@$PROJECT.iam.gserviceaccount.com --role roles/iam.workloadIdentityUser --member "serviceAccount:.svc.id.goog[endorlabs/endorlabs-compute-service]" ``` If you created a different service account name, replace `endorlabs-compute-service` with the appropriate name. ```bash theme={null} kubectl annotate serviceaccount endorlabs-compute-service -n endorlabs iam.gke.io/gcp-service-account=endorlabs-compute-service@$PROJECT.iam.gserviceaccount.com ``` Run a test scan to confirm keyless authentication is working correctly. ## Provision and Test Keyless Authentication for GCP Virtual Machine Instances The following instructions require you to export the following environment variable: ```bash theme={null} export PROJECT= ``` ```bash theme={null} gcloud compute instances create test-keyless --service-account endorlabs-compute-service@$PROJECT.iam.gserviceaccount.com --scopes https://www.googleapis.com/auth/cloud-platform ``` SSH to the virtual machine instance: ```bash theme={null} gcloud compute ssh --zone "us-west1-b" "test-keyless" --project $PROJECT ``` Then download and install the latest version of `endorctl`. See [our documentation for instructions on downloading the latest version](/developers-api/cli/install-and-configure). Use the `--gcp-service-account` flag for federated access to Endor Labs: ```bash theme={null} endorctl api list --gcp-service-account=endorlabs-federation@.iam.gserviceaccount.com -r Project -n --count ``` If this scan runs successfully you've tested and scanned a project with keyless authentication to Endor Labs. # Set up keyless authentication Source: https://docs.endorlabs.com/setup-deployment/ci-cd/keyless-authentication/index Learn how to implement keyless authentication for CI environments. At Endor Labs, we believe that the most secure secret is one that doesn't exist. That's why in CI/CD environments we recommend using keyless authentication for machine authentication. Keyless Authentication uses OAuth for API authentication and removes the need to maintain and rotate an API key to Endor Labs. Keyless Authentication is more secure and reduces the cost of secret rotation. Configure keyless authentication using: * [Google Cloud](/setup-deployment/ci-cd/keyless-authentication/google-keyless-auth) * [GitHub OIDC](/setup-deployment/ci-cd/keyless-authentication/github-keyless-auth) * [AWS Cloud](/setup-deployment/ci-cd/keyless-authentication/aws-keyless-auth) * [Azure](/setup-deployment/ci-cd/keyless-authentication/azure-keyless-auth) # Scanning in Azure Pipelines Source: https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-azuredevops/index Learn how to implement Endor Labs in an Azure Pipeline. Azure Pipelines is a continuous integration and continuous delivery (CI/CD) service available in Azure DevOps ecosystem. It facilitates continuous integration, continuous testing, and continuous deployment for seamless building, testing, and delivery of software. You can use Azure extension from Endor Labs to include Endor Labs within your Azure pipelines or add steps in your pipeline to manually download and use Endor Labs in your runner. ## Complete the prerequisites Ensure that you complete the following prerequisites before you proceed. ### Set up an Endor Labs tenant You must have an Endor Labs tenant set up for your organization. You can also set up namespaces according to your requirements. See [Set up namespaces](/platform-administration/namespaces) for more information. ### Configure Endor Labs authentication Configure an API key and secret for authentication. See [managing API keys](/platform-administration/api-keys) for more information on generating an API key for Endor Labs. Store API key and secret as environment variables, `ENDOR_API_CREDENTIALS_KEY` and `ENDOR_API_CREDENTIALS_SECRET`. ### Enable Advanced Security in Azure To view scan results directly in Azure DevOps, enable Advanced Security in your Azure repository. 1. Log in to Azure and open **Project Settings**. 2. Navigate to **Repos > Repositories** in the left navigation panel. 3. Select your repository. 4. Enable Advanced Security. Enable Advanced Security ## Integrate Endor Labs with Azure pipelines with the Azure extension To integrate Endor Labs with Azure pipelines, you need to set up the Azure extension. After you set up the extension, you can configure your pipeline to use Endor Labs. The Endor Labs Azure extension requires `code read`, `build read`, and `execute` permissions. ### Set up the Azure extension 1. Install the Endor Labs extension from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=endorlabs.endorlabs-security-scan-task). 2. Log in Azure DevOps and select your project. 3. Select **Project Settings** from the left sidebar. 4. Select **Service Connections** under **Pipelines**. 5. Click **Create service connection**. 6. Select **Endor Labs** and click **Next**. 7. Enter `https://api.endorlabs.com` as the **Server URL**. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. 8. Enter the **API Key** and **API Secret** that you [created](#configure-endor-labs-authentication). 9. Enter the service connection name. The name you enter here is to be used inside the Azure pipeline. 10. Optionally, you can enter service management reference and description. 11. Select **Grant access permission to all pipelines** to provide access to the Endor Labs service connection to your pipelines. Ensure that you select this option if you want to use Endor Labs with your pipelines. Unless you enable the service connection, Endor Labs will not be available to your pipelines. 12. Click **Save**. ### Configure Azure pipeline to use Endor Labs **Important** Azure Pipelines often check out commits in a detached HEAD state, which can lead to fragmented branch tracking in Endor Labs. See [Set up branch tracking in Azure Pipelines](#set-up-branch-tracking-in-azure-pipelines) to configure proper branch context. 1. Create `azure-pipelines.yml` file in your project, if it doesn't exist and enter values according to your requirement. 2. In the `azure-pipelines.yml` file, enter the task, `EndorLabsScan@0`, with the service connection name, Endor Labs namespace, and the SARIF file name. For example: ```yaml theme={null} steps: - task: EndorLabsScan@0 inputs: serviceConnectionEndpoint: 'Endor' namespace: 'demo' sarifFile: 'scanresults.sarif' ``` 3. Enter the task, `AdvancedSecurity-Publish@1`, if you wish to publish the scan results, which you can view under the Advanced Security tab in Azure DevOps. ```yaml theme={null} steps: - task: AdvancedSecurity-Dependency-Scanning@1 displayName: Publish scan dependencies to Advanced Security inputs: SarifsInputDirectory: $(Build.SourcesDirectory)\ ``` After a successful run of the pipeline, you can [view the results in Azure](#view-scan-results-in-azure). ### Endor Labs scan parameters You can use the following input parameters in the `EndorLabsScan@0` task. **AI SAST scan options** * To enable an AI SAST triage agent scan, set the `additionalArgs` parameter to `--ai-sast-analysis=agent-fallback`. * To enable an AI SAST detection agent scan, set the `additionalArgs` parameter to `--ai-sast`. ### Example Workflow The following example workflow initiates a scan where all dependencies are scanned along with secrets. The findings are tagged with `Azure`. The scan generates a SARIF file and uploads to GitHub Advanced Security. ```yaml expandable theme={null} trigger: - none pool: name: Azure Pipelines vmImage: "windows-latest" steps: - task: EndorLabsScan@0 inputs: serviceConnectionEndpoint: 'endorlabs-service-connection' namespace: 'endor' sarifFile: 'scanresults.sarif' scanSecrets: 'true' tags: `Azure` - task: AdvancedSecurity-Publish@1 displayName: Publish 'scanresults.sarif' to Advanced Security inputs: SarifsInputDirectory: $(Build.SourcesDirectory)\ ``` ## View scan results in Azure After the pipeline runs, you can view the scan results in Azure. 1. Log in to Azure and navigate to your projects. 2. Select **Repos** > **Advanced Security** to view the scan results. View Azure advanced security 3. Click an alert to view more details. View Azure alert 4. If you ran endorctl with `--secrets` flag, you can view if there are any secret leaks. View Azure secret leak Click the entry to view more details. View Azure secret leak expanded ## Block pull requests on pipeline scan findings A pipeline scan reports findings, but it does not block a merge on its own. When a finding matches an action policy set to **Break the Build**, the scan exits with [code 128](/best-practices/troubleshooting/endorctl-exitcodes) and the pipeline job fails. To turn that failure into a merge gate, add a build validation policy that requires the pipeline. See [Block merges for PR scans run from Azure Pipelines](/scan/pr-scans#block-merges-for-pr-scans-run-from-azure-pipelines) to configure the branch policy. ## Download and use endorctl in Azure pipeline You can also choose to set up your pipeline to download endorctl and scan using Endor Labs without using the Azure extension. ### Configure Endor Labs variables in the pipeline You can manage Endor Labs variables centrally by configuring them within your Azure project. You can assign these variables to multiple pipelines. 1. Log in to Azure and select **Pipelines > Library**. 2. Click **+Variable Group** to add a new variable group for Endor Labs. 3. Enter a name for the variable group, for example, `tenant-variables`, and click **Add** under **Variables**. 4. Add the following variables. * `ENDOR_API_CREDENTIALS_KEY` * `ENDOR_API_CREDENTIALS_SECRET` * `NAMESPACE` Create Variables 5. Select the variable group that you created. Create Variables 6. Click **Pipeline Permissions**. 7. Click **+** to add the pipelines in which you want to use the variable group. Create Variables ### Configure your Azure pipeline 1. Create `azure-pipelines.yml` file in your project, if it doesn't exist. 2. In the `azure-pipelines.yml` file, customize the job configuration based on your project's requirements. 3. Adjust the image field to use the necessary build tools for constructing your software packages, and align your build steps with those of your project. For example, update the node pool settings based on your operating system. ```yaml theme={null} pool: name: Default vmImage: "windows-latest" ``` ```yaml theme={null} pool: name: Default vmImage: "ubuntu-latest" ``` ```yaml theme={null} pool: name: Default vmImage: "macOS-latest" ``` 4. Update your default branch from main if you do not use main as the default branch name. 5. Modify any dependency or artifact caches to align with the languages and caches used by your project. 6. Enter the following steps in the `azure-pipelines.yml` file to download endorctl. ```yaml theme={null} - bash: | echo "Downloading latest version of endorctl" VERSION=$(curl https://api.endorlabs.com/meta/version | grep -o '"Version":"[^"]*"' | sed 's/.*"Version":"\([^"]*\)".*/\1/') curl https://api.endorlabs.com/download/endorlabs/"$VERSION"/binaries/endorctl_"$VERSION"_windows_amd64.exe -o endorctl.exe echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_windows_amd64.exe) endorctl" | sha256sum -c if [ $? -ne 0 ]; then echo "Integrity check failed" exit 1 fi ``` ```yaml theme={null} - bash: | echo "Downloading latest version of endorctl" VERSION=$(curl https://api.endorlabs.com/meta/version | grep -o '"Version":"[^"]*"' | sed 's/.*"Version":"\([^"]*\)".*/\1/') curl https://api.endorlabs.com/download/endorlabs/"$VERSION"/binaries/endorctl_"$VERSION"_linux_amd64 -o endorctl echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c if [ $? -ne 0 ]; then echo "Integrity check failed" exit 1 fi ``` ```yaml theme={null} - bash: | echo "Downloading latest version of endorctl" VERSION=$(curl https://api.endorlabs.com/meta/version | grep -o '"Version":"[^"]*"' | sed 's/.*"Version":"\([^"]*\)".*/\1/') curl https://api.endorlabs.com/download/endorlabs/"$VERSION"/binaries/endorctl_"$VERSION"_macos_arm64 -o endorctl echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_macos_arm64) endorctl" | shasum -a 256 --check if [ $? -ne 0 ]; then echo "Integrity check failed" exit 1 fi ``` 7. Enter the steps to build your project if your project needs building and setup steps. 8. Enter the following step in the `azure-pipelines.yml` file to run endorctl scan to generate the SARIF file. You can run endorctl scan with [options](/developers-api/cli/commands/scan) according to your requirement, but you must include the `-s` option to generate the SARIF file. For example, use the `--secrets` flag to scan for secrets. ```yaml theme={null} - script: | .\endorctl.exe scan -n $(NAMESPACE) -s scanresults.sarif env: ENDOR_API_CREDENTIALS_KEY: $(ENDOR_API_CREDENTIALS_KEY) ENDOR_API_CREDENTIALS_SECRET: $(ENDOR_API_CREDENTIALS_SECRET) ``` ```yaml theme={null} - script: | ./endorctl scan -n $(NAMESPACE) -s scanresults.sarif env: ENDOR_API_CREDENTIALS_KEY: $(ENDOR_API_CREDENTIALS_KEY) ENDOR_API_CREDENTIALS_SECRET: $(ENDOR_API_CREDENTIALS_SECRET) ``` ```yaml theme={null} - script: | ./endorctl scan -n $(NAMESPACE) -s scanresults.sarif env: ENDOR_API_CREDENTIALS_KEY: $(ENDOR_API_CREDENTIALS_KEY) ENDOR_API_CREDENTIALS_SECRET: $(ENDOR_API_CREDENTIALS_SECRET) ``` 9. Enter the following task in the `azure-pipelines.yml` to publish the scan results. ```yaml theme={null} - task: AdvancedSecurity-Publish@1 displayName: Publish '.\sarif\scanresults.sarif' to Advanced Security inputs: SarifsInputDirectory: $(Build.SourcesDirectory)\ ``` After a successful run of the pipeline, you can [view the results in Azure](#view-scan-results-in-azure). ### Azure Pipeline Examples ```yaml theme={null} trigger: - none pool: name: Azure Pipelines vmImage: "windows-latest" variables: - group: tenant-variables steps: # All steps related to building of the project should be before this step. # Implement and scan with Endor Labs after your build is complete. - bash: | - bash: | echo "Downloading latest version of endorctl" VERSION=$(curl https://api.endorlabs.com/meta/version | grep -o '"Version":"[^"]*"' | sed 's/.*"Version":"\([^"]*\)".*/\1/') curl https://api.endorlabs.com/download/endorlabs/"$VERSION"/binaries/endorctl_"$VERSION"_windows_amd64.exe -o endorctl.exe echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_windows_amd64.exe) endorctl" | sha256sum -c if [ $? -ne 0 ]; then echo "Integrity check failed" exit 1 fi displayName: 'Downloading latest version of endorctl' continueOnError: false - script: | .\endorctl.exe scan -n $(NAMESPACE) -s scanresults.sarif displayName: 'Run a scan against the repository using your API key & secret pair' env: ENDOR_API_CREDENTIALS_KEY: $(ENDOR_API_CREDENTIALS_KEY) ENDOR_API_CREDENTIALS_SECRET: $(ENDOR_API_CREDENTIALS_SECRET) - task: AdvancedSecurity-Publish@1 displayName: Publish '.\sarif\scanresults.sarif' to Advanced Security inputs: SarifsInputDirectory: $(Build.SourcesDirectory)\ ``` ```yaml theme={null} trigger: - none pool: name: Azure Pipelines vmImage: "ubuntu-latest" variables: - group: tenant-variables steps: # All steps related to building of the project should be before this step. # Implement and scan with Endor Labs after your build is complete. - bash: | - bash: | echo "Downloading latest version of endorctl" VERSION=$(curl https://api.endorlabs.com/meta/version | grep -o '"Version":"[^"]*"' | sed 's/.*"Version":"\([^"]*\)".*/\1/') curl https://api.endorlabs.com/download/endorlabs/"$VERSION"/binaries/endorctl_"$VERSION"_linux_amd64 -o endorctl echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c if [ $? -ne 0 ]; then echo "Integrity check failed" exit 1 fi ## Modify the permissions of the binary to ensure it is executable chmod +x ./endorctl ## Create an alias of the endorctl binary to ensure it is available in other directories alias endorctl="$PWD/endorctl" displayName: 'Downloading latest version of endorctl' continueOnError: false - script: | ./endorctl scan -n $(NAMESPACE) -s scanresults.sarif displayName: 'Run a scan against the repository using your API key & secret pair' env: ENDOR_API_CREDENTIALS_KEY: $(ENDOR_API_CREDENTIALS_KEY) ENDOR_API_CREDENTIALS_SECRET: $(ENDOR_API_CREDENTIALS_SECRET) - task: AdvancedSecurity-Publish@1 displayName: Publish '.\sarif\scanresults.sarif' to Advanced Security inputs: SarifsInputDirectory: $(Build.SourcesDirectory)/ ``` ```yaml theme={null} trigger: - none pool: name: Azure Pipelines vmImage: "macos-latest" variables: - group: tenant-variables steps: # All steps related to building of the project should be before this step. # Implement and scan with Endor Labs after your build is complete. - bash: | echo "Downloading latest version of endorctl" VERSION=$(curl https://api.endorlabs.com/meta/version | grep -o '"Version":"[^"]*"' | sed 's/.*"Version":"\([^"]*\)".*/\1/') curl https://api.endorlabs.com/download/endorlabs/"$VERSION"/binaries/endorctl_"$VERSION"_macos_arm64 -o endorctl echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_macos_arm64) endorctl" | shasum -a 256 --check if [ $? -ne 0 ]; then echo "Integrity check failed" exit 1 fi ## Modify the permissions of the binary to ensure it is executable chmod +x ./endorctl ## Create an alias of the endorctl binary to ensure it is available in other directories alias endorctl="$PWD/endorctl" displayName: 'Downloading latest version of endorctl' continueOnError: false - script: | ./endorctl scan -n $(NAMESPACE) -s scanresults.sarif displayName: 'Run a scan against the repository using your API key & secret pair' env: ENDOR_API_CREDENTIALS_KEY: $(ENDOR_API_CREDENTIALS_KEY) ENDOR_API_CREDENTIALS_SECRET: $(ENDOR_API_CREDENTIALS_SECRET) - task: AdvancedSecurity-Publish@1 displayName: Publish '.\sarif\scanresults.sarif' to Advanced Security inputs: SarifsInputDirectory: $(Build.SourcesDirectory)/ ``` ## Set up branch tracking in Azure Pipelines In Git, a detached HEAD state occurs when the repository checks out a specific commit instead of a branch reference. In this state, Git points the HEAD directly to a commit hash, without associating it with a named branch. As a result, actions performed, such as creating new commits or running automated scans, do not carry branch identity unless explicitly specified. Proper branch context enables Endor Labs to: * Associate scans with the correct branch * Identify scans on the monitored default branch * Track findings and display metrics accurately across branches Without proper branch configuration, Endor Labs may create multiple branch entries for the same logical branch, leading to fragmented reporting and inaccurate metrics. Project with multiple branch entries Azure Pipelines often check out commits by their SHA instead of the branch name, which creates a detached HEAD state. ### Automatic branch tracking When you use the Endor Labs Azure extension, branch tracking is automated. The `enableDetachedRefName` parameter is set to `true` by default, which automatically detects the branch name from your Azure pipeline and appends the `--detached-ref-name` flag during scans. This ensures that scans display the actual branch name instead of the commit SHA. ```yaml theme={null} steps: - task: EndorLabsScan@0 inputs: namespace: 'demo' sarifFile: 'scanresults.sarif' serviceConnectionEndpoint: 'Endor' ``` To disable automatic branch tracking and use the commit SHA instead, explicitly set `enableDetachedRefName` to `false`. ```yaml theme={null} steps: - task: EndorLabsScan@0 inputs: enableDetachedRefName: false namespace: 'demo' sarifFile: 'scanresults.sarif' serviceConnectionEndpoint: 'Endor' ``` ### Manual branch tracking with endorctl When you use endorctl, specify the branch name using the `--detached-ref-name` flag. Use `--detached-ref-name` only to specify the branch name for a commit in detached HEAD state. This associates the commit with the correct branch without setting it as the default branch. ```yaml theme={null} - script: | BRANCH_NAME=$(Build.SourceBranchName) ./endorctl scan -n $(NAMESPACE) \ --detached-ref-name="$BRANCH_NAME" \ -s scanresults.sarif ``` Use both `--detached-ref-name` and `--as-default-branch` together when you want to associate the commit with a branch and set it as the default branch scan. ```yaml theme={null} - script: | BRANCH_NAME=$(Build.SourceBranchName) ./endorctl scan -n $(NAMESPACE) \ --as-default-branch \ --detached-ref-name="$BRANCH_NAME" \ -s scanresults.sarif ``` # Scanning in Bitbucket Pipelines Source: https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-bitbucket/index Learn how to implement Endor Labs in a Bitbucket pipeline. Bitbucket Pipelines is a continuous integration and continuous delivery (CI/CD) service built into Bitbucket. It allows developers to automatically build, test, and deploy their code based on a configuration file `bitbucket-pipelines.yml` defined in the root of their repository. To integrate Endor Labs into a Bitbucket pipeline: 1. [Authenticate to Endor Labs](#authenticate-to-endor-labs) 2. Install your build toolchain 3. Build your code 4. Scan with Endor Labs ## Authenticate to Endor Labs Configure an API key and secret in the `bitbucket-pipelines.yml` file for authentication. See [managing API keys](/platform-administration/api-keys) for more information on generating an API key for Endor Labs. ## Configure your Bitbucket pipeline **Important** Bitbucket Pipelines may check out commits in a detached HEAD state, which can lead to fragmented branch tracking in Endor Labs. See [Set up branch tracking in Bitbucket Pipelines](#set-up-branch-tracking-in-bitbucket-pipelines) to configure proper branch context. To create a Bitbucket pipeline reference the following steps: 1. Create a `bitbucket-pipelines.yml` file in your repository if you do not already have one. 2. In your `bitbucket-pipelines.yml` file customize the job configuration based on your project's requirements using [the following example](#example). 3. Adjust the image field to use the necessary build tools for constructing your software packages, and align your build steps with those of your project. 4. Update your Endor Labs tenant namespace to the appropriate namespace for your project. 5. Update your default branch from main if you do not use main as the default branch name. 6. Modify any dependency or artifact caches to align with the languages and caches used by your project. ## Example Use the following example to get started. Make sure to customize this job with your specific build environment and build steps. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ### Bitbucket configuration ```yaml expandable theme={null} simage: maven:3.6.3-jdk-11 pipelines: branches: main: - step: name: "Build and Test" script: - mvn install -DskipTests - echo "Running Endor Labs Scan" - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl - echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c - chmod +x ./endorctl - ./endorctl scan -n $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET pull-requests: '**': - step: name: "Build and Test on PR to Main" script: - mvn install -DskipTests - echo "Running Endor Labs PR Scan" - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl - echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c - chmod +x ./endorctl - ./endorctl scan --pr --pr-baseline=main --languages=java --output-type=json -n $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET | tee output.json #Optional - Comment on the PR # - apt-get update # - apt-get install -y python3 python3-pip # - pip3 install -r requirements.txt # - python3 add-bitbucket-pr-comments.py output.json ``` Once you've set up Endor Labs, you can test your CI implementation to ensure it is successful and then proceed with your scans. ### View PR comments for policy violations You can also use the Insights feature in Bitbucket Pipelines to indicate if the changes in your pull requests violated any policies set in Endor Labs. ```bash expandable theme={null} import json import os import sys import requests import argparse # Check for required environment variables BITBUCKET_REPO_OWNER = os.getenv('BITBUCKET_REPO_OWNER') BITBUCKET_REPO_SLUG = os.getenv('BITBUCKET_REPO_SLUG') BITBUCKET_COMMIT = os.getenv('BITBUCKET_COMMIT') if not all([BITBUCKET_REPO_OWNER, BITBUCKET_REPO_SLUG, BITBUCKET_COMMIT]): sys.exit("Error: One or more required environment variables (BITBUCKET_REPO_OWNER, BITBUCKET_REPO_SLUG, BITBUCKET_COMMIT) are not set.") #This is an internal proxy running in the BitBucket environment to accept Code Insights proxies = {"http": "http://localhost:29418"} def load_json_with_unescaped_characters(file_path): """Load and return JSON data from a file, replacing unescaped characters if necessary.""" try: with open(file_path, 'r', encoding='utf-8') as file: json_str = file.read().strip() return json.loads(json_str) except json.decoder.JSONDecodeError as e: print(f"Failed to parse JSON: {e}") return None except FileNotFoundError: print(f"File not found: {file_path}") sys.exit() def construct_report_payload(endor_findings): """Construct and return the payload for creating a Bitbucket report.""" warning_findings_count = len(endor_findings.get('warning_findings', [])) blocking_findings_count = len(endor_findings.get('blocking_findings', [])) total_violations = warning_findings_count + blocking_findings_count result = "PASSED" if total_violations == 0 else "FAILED" report_payload = { "title": "Endor Labs Policy Violations", "details": f"Endor Labs detected {total_violations} policy violations associated with this pull request.\n\n{endor_findings['warnings'][0]}", "report_type": "SECURITY", "reporter": "Endor Labs", "link": f"https://app.endorlabs.com/t/{namespace}/projects/{project_uuid}/pr-runs/{report_id}", "logo_url": "https://avatars.githubusercontent.com/u/92199924", "result": result, "data": [ {"title": "Warning Findings", "type": "NUMBER", "value": warning_findings_count}, {"title": "Blocking Findings", "type": "NUMBER", "value": blocking_findings_count} ] } return report_payload def construct_annotation_payload(finding): """Construct and return the payload for creating an annotation in Bitbucket.""" title = "Endor Labs Policy Violation" summary = finding['meta']['description'] details = f"{finding['spec']['summary']}\n\n{finding['spec']['remediation']}" severity = "CRITICAL" if finding['spec']['level'] == "FINDING_LEVEL_CRITICAL" else \ "HIGH" if finding['spec']['level'] == "FINDING_LEVEL_HIGH" else \ "MEDIUM" if finding['spec']['level'] == "FINDING_LEVEL_MEDIUM" else "LOW" affected_paths = finding['spec'].get('dependency_file_paths', []) path = affected_paths[0] if affected_paths else "Unknown file" annotation_payload = { "external_id": finding['uuid'], "title": title, "annotation_type": "VULNERABILITY", "summary": summary, "details": details, "severity": severity, "path": path } return annotation_payload def send_report(report_payload): """Send the constructed report payload to the Bitbucket API.""" report_url = f"http://api.bitbucket.org/2.0/repositories/{BITBUCKET_REPO_OWNER}/{BITBUCKET_REPO_SLUG}/commit/{BITBUCKET_COMMIT}/reports/{report_id}" response = requests.put(report_url, json=report_payload, proxies=proxies) if response.status_code in [200, 201]: print("Report created or updated successfully") else: print(f"Failed to create or update report: {response.text}") def send_annotation(annotation_payload): """Send the constructed annotation payload to the Bitbucket API.""" annotation_url = f"{base_url}/{report_id}/annotations/{annotation_payload['external_id']}" response = requests.put(annotation_url, json=annotation_payload, proxies=proxies) if response.status_code in [200, 201]: print("Annotation added successfully") else: print(f"Failed to add annotation: {response.text}") def process_findings(filename): """Load findings from JSON, create a report, and add annotations for each finding.""" endor_findings = load_json_with_unescaped_characters(filename) if endor_findings is None: print("Failed to load findings. Exiting.") return global report_id, project_uuid, namespace # Define the order of keys to check finding_types = ['all_findings', 'warning_findings', 'blocking_findings'] # Iterate over finding types and extract the first one found for finding_type in finding_types: if endor_findings.get(finding_type): first_finding = endor_findings[finding_type][0] report_id = first_finding['context']['id'] project_uuid = first_finding['spec']['project_uuid'] namespace = first_finding['tenant_meta']['namespace'] break # Stop after finding the first non-empty list if not report_id: print("No findings found.") sys.exit() # Prepare the base URL for Bitbucket API requests global base_url base_url = f"http://api.bitbucket.org/2.0/repositories/{BITBUCKET_REPO_OWNER}/{BITBUCKET_REPO_SLUG}/commit/{BITBUCKET_COMMIT}/reports" # Create the report report_payload = construct_report_payload(endor_findings) send_report(report_payload) # Iterate over findings and create annotations for finding in endor_findings.get('blocking_findings', []) + endor_findings.get('warning_findings', []): annotation_payload = construct_annotation_payload(finding) send_annotation(annotation_payload) def main(): """Main function to parse arguments and process findings.""" parser = argparse.ArgumentParser(description="Script to process findings and update Bitbucket via API.") parser.add_argument("filename", help="Filename containing the JSON findings.") args = parser.parse_args() process_findings(args.filename) if __name__ == "__main__": main() ``` ## SAST scans in Bitbucket Pipelines You can run SAST scans in your Bitbucket pipeline to identify security vulnerabilities and code quality issues in your source code. SAST scanning analyzes your source code for potential security weaknesses based on enabled rules and generates findings based on your configured finding policies. ### SAST scan To run a SAST scan, add the `--sast` flag to your endorctl scan command. ```yaml theme={null} script: - ./endorctl scan -n $ENDOR_NAMESPACE --sast \ --api-key $ENDOR_API_CREDENTIALS_KEY \ --api-secret $ENDOR_API_CREDENTIALS_SECRET ``` ### AI SAST triage agent scan To run an AI SAST triage agent scan, add the `--sast` and `--ai-sast-analysis=agent-fallback` flags to your endorctl scan command. The AI SAST triage agent automatically classifies findings as true positives or false positives, reducing the need for manual triage. ```yaml theme={null} script: - ./endorctl scan -n $ENDOR_NAMESPACE --sast --ai-sast-analysis=agent-fallback \ --api-key $ENDOR_API_CREDENTIALS_KEY \ --api-secret $ENDOR_API_CREDENTIALS_SECRET ``` To re-analyze all findings, including those that have already been analyzed, add the `--ai-sast-rescan` flag. ### AI SAST detection agent scan To run an AI SAST detection agent scan, add the `--ai-sast` flag to your endorctl scan command. The AI SAST detection agent identifies security vulnerabilities beyond traditional rule-based SAST detection. ```yaml theme={null} script: - ./endorctl scan -n $ENDOR_NAMESPACE --ai-sast \ --api-key $ENDOR_API_CREDENTIALS_KEY \ --api-secret $ENDOR_API_CREDENTIALS_SECRET ``` ### AI SAST PR scan To run an AI SAST PR scan, add the `--ai-sast`, `--pr`, and `--pr-baseline` flags to your endorctl scan command. The scan analyzes only the code changed by the pull request and surfaces the net new findings introduced by the change. A baseline AI SAST scan must exist on the target branch first. See [AI SAST PR scans](/scan/ai-sast/ai-sast-pr-scans) to learn more. ```yaml theme={null} script: - ./endorctl scan -n $ENDOR_NAMESPACE --ai-sast --pr --pr-baseline=main \ --api-key $ENDOR_API_CREDENTIALS_KEY \ --api-secret $ENDOR_API_CREDENTIALS_SECRET ``` ## Set up branch tracking in Bitbucket Pipelines In Git, a detached HEAD state occurs when the repository checks out a specific commit instead of a branch reference. In this state, Git points the HEAD directly to a commit hash, without associating it with a named branch. As a result, actions performed, such as creating new commits or running automated scans, do not carry branch identity unless explicitly specified. Proper branch context enables Endor Labs to: * Associate scans with the correct branch * Identify scans on the monitored default branch * Track findings and display metrics accurately across branches Without proper branch configuration, Endor Labs may create multiple branch entries for the same logical branch, leading to fragmented reporting and inaccurate metrics. Project with multiple branch entries Bitbucket Pipelines often check out commits by their SHA instead of the branch name, which creates a detached HEAD state. Use `--detached-ref-name` only to specify the branch name for a commit in detached HEAD state. This associates the commit with the correct branch without setting it as the default branch. ```yaml theme={null} script: - ./endorctl scan -n $ENDOR_NAMESPACE \ --detached-ref-name="$BITBUCKET_BRANCH" \ --api-key $ENDOR_API_CREDENTIALS_KEY \ --api-secret $ENDOR_API_CREDENTIALS_SECRET ``` Use both `--detached-ref-name` and `--as-default-branch` together when you want to associate the commit with a branch and set it as the default branch scan. ```yaml theme={null} script: - ./endorctl scan -n $ENDOR_NAMESPACE \ --as-default-branch \ --detached-ref-name="$BITBUCKET_BRANCH" \ --api-key $ENDOR_API_CREDENTIALS_KEY \ --api-secret $ENDOR_API_CREDENTIALS_SECRET ``` # Scanning with Buildkite Source: https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-buildkite/index Learn how to implement Endor Labs in Buildkite pipelines. Buildkite runs CI/CD pipelines on agents that you host. Use the [Endor Labs Buildkite plugin](https://github.com/endorlabs/endorlabs-buildkite-plugin) to scan your code from any Buildkite step. The plugin runs as a single Buildkite `post-command` hook. Your step's `command` runs first, then the plugin installs endorctl, authenticates to Endor Labs, and runs the scan. The plugin supports the same scan options and outputs as the [Endor Labs GitHub Action](/setup-deployment/ci-cd/scan-with-github-actions). To integrate Endor Labs into your Buildkite pipelines: 1. [Install the plugin](#install-the-plugin) 2. [Authenticate to Endor Labs](#authenticate-to-endor-labs) 3. [Configure your pipeline](#configure-your-pipeline) ## Before you begin Ensure that you complete the following prerequisites before you proceed. * Have the value of your Endor Labs tenant namespace handy. * Generate an Endor Labs API key and secret, or use a cloud identity for keyless authentication. See [Managing API keys](/platform-administration/api-keys) to create credentials. * Install `jq` on your agents if you turn on build annotations. * On Windows agents, install Git Bash. The plugin hooks delegate to Bash. The plugin installs endorctl only. Install your build toolchain, such as Java, Node.js, or Bazel, on the agent image or in your step's `command`. ## Install the plugin You can vendor the plugin into your repository or reference the public Git repository in your pipeline. Vendoring gives you a reviewed, pinned copy that also works in air-gapped environments. ### Vendor the plugin 1. Clone the plugin repository at the latest release tag. ```bash theme={null} git clone --depth 1 --branch \ https://github.com/endorlabs/endorlabs-buildkite-plugin.git /tmp/endorlabs-buildkite-plugin ``` 2. Copy the sync script into your repository. ```bash theme={null} cp /tmp/endorlabs-buildkite-plugin/scripts/sync-vendor-endorlabs-plugin.sh scripts/ ``` 3. Run the sync script from your repository root. ```bash theme={null} ENDORLABS_PLUGIN_SRC=/tmp/endorlabs-buildkite-plugin ./scripts/sync-vendor-endorlabs-plugin.sh ``` The script copies the plugin runtime files into `.buildkite/vendor/endorlabs-buildkite-plugin` and writes a `VENDOR_SOURCE.json` record with the source commit. 4. Commit the vendored plugin and the sync script. ```bash theme={null} git add scripts/sync-vendor-endorlabs-plugin.sh .buildkite/vendor/endorlabs-buildkite-plugin ``` 5. Reference the vendored plugin in your pipeline steps. ```yaml theme={null} plugins: - ./.buildkite/vendor/endorlabs-buildkite-plugin: namespace: "${ENDOR_NAMESPACE}" ``` To update the plugin, run the sync script again from a newer checkout and commit the changes. ### Reference the public Git repository Reference the plugin directly from GitHub, pinned to a release tag. Copy the current pinned reference from the card above. ```yaml theme={null} plugins: - https://github.com/endorlabs/endorlabs-buildkite-plugin.git#: namespace: "${ENDOR_NAMESPACE}" ``` ## Authenticate to Endor Labs The plugin reads credentials from environment variables on the agent. You pass the variable names, not the values, so secrets never appear in your pipeline YAML or on the endorctl command line. ### Use API credentials Store your credentials as Buildkite cluster secrets: 1. In Buildkite, go to **Agents** > your cluster > **Secrets**. 2. Create a secret named `ENDOR_API_CREDENTIALS_KEY` with your API key as the value. 3. Create a secret named `ENDOR_API_CREDENTIALS_SECRET` with your API key secret as the value. 4. Optional: Create a secret named `ENDOR_NAMESPACE` with your tenant namespace to keep it out of your pipeline YAML. Expose the secrets to your build and pass the variable names to the plugin: ```yaml theme={null} secrets: - ENDOR_NAMESPACE - ENDOR_API_CREDENTIALS_KEY - ENDOR_API_CREDENTIALS_SECRET steps: - label: "Build and scan" command: "make build" plugins: - ./.buildkite/vendor/endorlabs-buildkite-plugin: namespace: "${ENDOR_NAMESPACE}" api_key_env: ENDOR_API_CREDENTIALS_KEY api_secret_env: ENDOR_API_CREDENTIALS_SECRET ``` For more information, refer to [Buildkite cluster secrets](https://buildkite.com/docs/agent/v3/clusters/secrets). ### Use keyless authentication If your agents run in AWS, GCP, or Azure, you can authenticate without storing Endor Labs API credentials: * Set `aws_role_arn` on agents with ambient AWS credentials, such as an EC2 instance profile or EKS IRSA. * Set `gcp_service_account` to your Endor Labs federation service account on GCP agents. * Set `enable_azure_managed_identity: true` on Azure agents with a managed identity. Each cloud option is mutually exclusive with API credentials. See [Keyless authentication](/setup-deployment/ci-cd/keyless-authentication) to set up an authorization policy for your cloud identity. endorctl doesn't accept Buildkite OIDC tokens for authentication, and GitHub keyless authentication works only in GitHub Actions. On Buildkite, use API credentials or cloud keyless authentication on the agent. Buildkite agents can issue OIDC tokens with `buildkite-agent oidc` to federate with cloud providers. On AWS, you can exchange that token for AWS credentials and then set `aws_role_arn`, so the AWS identity authenticates to Endor Labs. For more information, refer to [OIDC with AWS in Buildkite](https://buildkite.com/docs/pipelines/security/oidc/aws). ## Configure your pipeline The following example builds a project and scans it for dependency and secrets findings, with a build annotation for the results. ```yaml expandable theme={null} secrets: - ENDOR_NAMESPACE - ENDOR_API_CREDENTIALS_KEY - ENDOR_API_CREDENTIALS_SECRET steps: - label: ":hammer: Build and scan" command: "mvn clean install" plugins: - ./.buildkite/vendor/endorlabs-buildkite-plugin: namespace: "${ENDOR_NAMESPACE}" api_key_env: ENDOR_API_CREDENTIALS_KEY api_secret_env: ENDOR_API_CREDENTIALS_SECRET scan_dependencies: true scan_secrets: true annotate: true ``` Customize the example for your project: 1. Replace `command` with your project's build steps. The scan starts after the command completes. 2. Replace the plugin reference with the pinned public Git reference if you don't vendor the plugin. 3. Turn on the scan types you need, such as `scan_sast` or `scan_secrets`. To verify the integration, run the pipeline and confirm that the build log shows `Running endorctl scan`. ## Set up PR scans and branch tracking The plugin reads the Buildkite build environment and passes branch and pull request context to endorctl automatically: Buildkite agents often check out commits in a detached HEAD state. You don't need to configure branch tracking manually because the plugin passes the branch name from `BUILDKITE_BRANCH`. Builds for pull requests run as PR scans. On other builds, Buildkite sets `BUILDKITE_PULL_REQUEST` to `false` and the scan records a monitored version. Set `pr: false` to record a monitored scan even on a pull request build, or set `pr_baseline` to force a PR scan without one. See [PR scans](/scan/pr-scans) to learn how Endor Labs tracks point-in-time scans. To post new findings as pull request comments, set `enable_pr_comments: true` and set `scm_token_env` to the name of an environment variable that holds your SCM token. The token must be a personal access token or bot token from your SCM provider. See [PR comments](/scan/pr-scans/pr-comments) to learn how comments appear on pull requests. ## Annotate builds with scan results Set `annotate: true` to post a build annotation when the scan completes. The annotation shows severity counts, admission policy status, and a findings table scoped to the scan types enabled on that step. Annotations require `jq` on the agent and the default JSON output. Use `annotate_findings_limit` to control the table size. The value `-1` lists all critical and high findings, `0` shows severity counts only, and a positive number adds up to that many medium and low rows. Buildkite build with parallel Endor Labs scan steps and a job-scoped dependencies scan annotation showing severity counts, admission policy status, and a findings table In pipelines that run scan types in parallel steps, set `annotate_scope: job` to attach each annotation to its own step. Job-scoped annotations require Buildkite agent v3.112 or later. ## Control build failures When a blocking admission policy matches, endorctl exits with code `128` and the step fails. This is the default behavior, controlled by `fail_on_policy: true`. * Set `fail_on_policy: false` to treat a blocking admission policy as success. * Set `soft_fail: true` to soften other nonzero exits. It doesn't bypass exit `128` while `fail_on_policy` is `true`. * Set `exit_on_policy_warning: true` to also fail the step on warning policies. See [endorctl exit codes](/best-practices/troubleshooting/endorctl-exitcodes) for the full list of exit codes. ## Run SAST scans ### SAST scan Set `scan_sast: true` to scan your source code for security weaknesses. ```yaml theme={null} plugins: - ./.buildkite/vendor/endorlabs-buildkite-plugin: namespace: "${ENDOR_NAMESPACE}" api_key_env: ENDOR_API_CREDENTIALS_KEY api_secret_env: ENDOR_API_CREDENTIALS_SECRET scan_sast: true ``` ### AI SAST triage agent scan To run an AI SAST triage agent scan, set `scan_sast: true` and set `additional_args` to `--ai-sast-analysis=agent-fallback`. The AI SAST triage agent automatically classifies findings as true positives or false positives, reducing the need for manual triage. ```yaml theme={null} plugins: - ./.buildkite/vendor/endorlabs-buildkite-plugin: namespace: "${ENDOR_NAMESPACE}" api_key_env: ENDOR_API_CREDENTIALS_KEY api_secret_env: ENDOR_API_CREDENTIALS_SECRET scan_sast: true additional_args: "--ai-sast-analysis=agent-fallback" ``` ### AI SAST detection agent scan To run an AI SAST detection agent scan, set `additional_args` to `--ai-sast`. The AI SAST detection agent identifies security vulnerabilities beyond traditional rule-based SAST detection. ```yaml theme={null} plugins: - ./.buildkite/vendor/endorlabs-buildkite-plugin: namespace: "${ENDOR_NAMESPACE}" api_key_env: ENDOR_API_CREDENTIALS_KEY api_secret_env: ENDOR_API_CREDENTIALS_SECRET additional_args: "--ai-sast" ``` See [SAST scans](/scan/sast) to learn about rules and findings. ## Scan container images Container scans run in a separate step from repository scans. Set `scan_container: true` with an `image` or `image_tar`, and turn off `scan_dependencies`. ```yaml theme={null} - label: ":docker: Scan container image" command: "docker build -t my-app:latest ." plugins: - ./.buildkite/vendor/endorlabs-buildkite-plugin: namespace: "${ENDOR_NAMESPACE}" api_key_env: ENDOR_API_CREDENTIALS_KEY api_secret_env: ENDOR_API_CREDENTIALS_SECRET scan_container: true scan_dependencies: false image: "my-app:latest" project_name: "my-app" ``` Set `os_reachability: true` to identify which packages in the image are used at runtime. See [Scan container images](/scan/containers/scan-containers-using-endorctl) and [Container reachability](/scan/containers/container-reachability) for details. ## Sign and verify artifacts Set `mode: sign` or `mode: verify` with an `artifact_name` to run artifact signing workflows instead of a scan. Scan options aren't valid in these modes. See [Artifact signing](/scan/containers/artifact-signing) to learn about signing and verification. ## Plugin configuration reference The following tables load directly from the plugin's [plugin.yml](https://github.com/endorlabs/endorlabs-buildkite-plugin/blob/main/plugin.yml) at the latest release, so they always reflect the current plugin version. ### Common options These options apply to every plugin invocation. Only `namespace` is required. ### Authentication options Use one authentication method per step: API credentials or one cloud keyless option. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ### Scan types Turn on at least one scan type when `mode` is `scan`. ### Scan configuration options These options adjust what a scan covers and how projects are named and tagged. ### Container scan options These options apply when `scan_container` is `true`. ### PR scan options These options control PR scan detection. ### Annotation and output options These options control build annotations, output formats, and uploaded artifacts. ### Build failure options These options decide when a scan fails the step. ### Artifact signing options These options apply when `mode` is `sign` or `verify`. # Scanning with CircleCI Source: https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-circleci/index Learn how to implement Endor Labs in a CircleCI pipeline. CircleCI CI/CD pipelines allow you to configure your pipeline as code. Your entire CI/CD process is orchestrated through a single file called `config.yml`. The `config.yml` file is located in a folder called `.circleci` at the root of your project which defines the entire pipeline. To integrate Endor Labs into your CircleCI CI/CD processes: 1. [Authenticate to Endor Labs](#authenticate-to-endor-labs) 2. Install your build toolchain 3. Build your code 4. Scan with Endor Labs ## Authenticate to Endor Labs Endor Labs recommends using keyless authentication in continuous integration environments. Keyless Authentication is more secure and reduces the cost of secret rotation but is **only available on self-hosted runners in CircleCI.** To configure keyless authentication see [the keyless authentication documentation](/setup-deployment/ci-cd/keyless-authentication) If you choose not to use keyless authentication you can configure an API key and secret in CircleCI for authentication using the following steps. See [managing API keys](/platform-administration/api-keys) for more information on generating an API key for Endor Labs. 1. In your CircleCI environment, navigate to **Organizational Settings**. 2. From **Contexts** and select **Create Context**. 3. Enter a context name for reference such as `endorlabs` or reuse an existing context. 4. Click into your new or existing context. Add any project restrictions and select **Add Environment Variable**. 5. In **Environment Variable Name**, enter **ENDOR\_API\_CREDENTIALS\_KEY** and in **Value**, enter the Endor Labs API Key. 6. Select **Add Environment Variable**. 7. Repeat the previous 3 steps to add your **API key secret** as the environment variable **ENDOR\_API\_CREDENTIALS\_SECRET**. Have the name of the context handy to reference in the workflows later. ## Configure your CircleCI pipeline **Important** CircleCI may check out commits in a detached HEAD state, which can lead to fragmented branch tracking in Endor Labs. See [Set up branch tracking in CircleCI](#set-up-branch-tracking-in-circleci) to configure proper branch context. To create a CircleCI pipeline reference the following steps: 1. Create a `.cirlceci/config.yml` file in your repository if you do not already have one. 2. In your `config.yml` file customize the job configuration based on your project's requirements using one of the examples, [simple CircleCI configuration](#simple-circleci-configuration) or [advanced CircleCI configuration](#advanced-circleci-configuration). 3. Create two workflows called `build_and_watch_endorlabs` and `build_and_test_endorlabs`. 4. Ensure that the context you created is part of the workflow if you are not using keyless authentication. 5. Adjust the image field to conform to the required build tools for constructing your software packages, and synchronize your build steps with those of your project. 6. Update your Endor Labs tenant namespace to the appropriate namespace for your project. 7. Update your default branch from main if you do not use main as the default branch name. 8. Modify any dependency or artifact caches to align with the languages and caches used by your project. ## Examples Use the following examples to get started. Make sure to customize this job with your specific build environment and build steps. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ### Simple CircleCI configuration ```yaml expandable theme={null} version: 2.1 jobs: test-endorlabs-scan: docker: - image: maven:3.6.3-jdk-11 # Modify this image as needed for your build tools environment: ENDORCTL_VERSION: "latest" ENDOR_NAMESPACE: "example" steps: - checkout - run: name: "Build" command: | mvn clean install -Dskiptests - run: name: "Install endorctl" command: | curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c; if [ $? -ne 0 ]; then echo "Integrity check failed"; exit 1; fi chmod +x ./endorctl ./endorctl --version - run: name: "Endor Labs Test" command: | ./endorctl scan --pr --pr-baseline=main --dependencies --secrets watch-endorlabs-scan: docker: - image: maven:3.6.3-jdk-11 # Modify this image as needed for your build tools environment: ENDOR_NAMESPACE: "example" # Replace with your Endor Labs namespace steps: - checkout - run: name: "Build" command: | mvn clean install -Dskiptests - run: name: "Install endorctl" command: | curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c; if [ $? -ne 0 ]; then echo "Integrity check failed"; exit 1; fi chmod +x ./endorctl ./endorctl --version - run: name: "Endor Labs Watch" command: | ./endorctl scan --dependencies --secrets workflows: build_and_endorlabs_watch: when: equal: [ main, << pipeline.git.branch >> ] jobs: - watch-endorlabs-scan: context: - endorlabs build_and_endorlabs_test: jobs: - test-endorlabs-scan: context: - endorlabs ``` ### Advanced CircleCI configuration The following example is an advanced implementation of Endor Labs in CircleCI which includes multiple optional performance optimizations and job maintainability updates. This includes: 1. Caching and restoring caches of jobs and artifacts to improve performance. Caches should be modified to reflect the build artifacts and dependencies of your project. 2. Segmenting jobs and scans. ```yaml expandable theme={null} # You can copy and paste portions of this `config.yml` file as an easy reference. # version: 2.1 jobs: build: docker: - image: maven:3.6.3-jdk-11 # Modify this image as needed for your build steps steps: - checkout - restore_cache: keys: # when lock file changes, use increasingly general patterns to restore cache - maven-repo-v1-{{ .Branch }}-{{ checksum "pom.xml" }} - maven-repo-v1-{{ .Branch }}- - maven-repo-v1- - run: name: "Build Your Project" command: | mvn clean install - persist_to_workspace: root: . paths: - target/ # Persist artifact across job. Change this if you are creating your artifact in a location outside of the target directory. - save_cache: paths: - ~/.m2/repository key: maven-repo-v1-{{ .Branch }}-{{ checksum "pom.xml" }} test-endorlabs-scan: docker: - image: maven:3.6.3-jdk-11 # Modify this image as needed for your build tools environment: ENDORCTL_VERSION: "latest" ENDOR_NAMESPACE: "example" steps: - checkout - attach_workspace: at: . - restore_cache: keys: # when lock file changes, use increasingly general patterns to restore cache - maven-repo-v1-{{ .Branch }}-{{ checksum "pom.xml" }} - maven-repo-v1-{{ .Branch }}- - maven-repo-v1- - run: name: "Install endorctl" command: | curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c; if [ $? -ne 0 ]; then echo "Integrity check failed"; exit 1; fi chmod +x ./endorctl ./endorctl --version - run: name: "Endor Labs Test" command: | ./endorctl scan --pr --pr-baseline=main --dependencies --secrets watch-endorlabs-scan: docker: - image: maven:3.6.3-jdk-11 # Modify this image as needed for your build tools environment: ENDORCTL_VERSION: "latest" ENDOR_NAMESPACE: "example" #Replace with your namespace in Endor Labs steps: - checkout - attach_workspace: at: . - restore_cache: keys: # when lock file changes, use increasingly general patterns to restore cache - maven-repo-v1-{{ .Branch }}-{{ checksum "pom.xml" }} - maven-repo-v1-{{ .Branch }}- - maven-repo-v1- - run: name: "Install endorctl" command: | curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c; if [ $? -ne 0 ]; then echo "Integrity check failed"; exit 1; fi chmod +x ./endorctl ./endorctl --version - run: name: "Endor Labs Watch" command: | ./endorctl scan --dependencies --secrets workflows: build_and_endorlabs_watch: when: equal: [ main, << pipeline.git.branch >> ] jobs: - build - watch-endorlabs-scan: requires: - build context: - endorlabs build_and_endorlabs_test: jobs: - build - test-endorlabs-scan: requires: - build context: - endorlabs ``` Once you've set up Endor Labs you can test your CI implementation is successful and begin scanning. ## SAST scans in CircleCI You can run SAST scans in your CircleCI pipeline to identify security vulnerabilities and code quality issues in your source code. SAST scanning analyzes your source code for potential security weaknesses based on enabled rules and generates findings based on your configured finding policies. ### SAST scan To run a SAST scan, add the `--sast` flag to your endorctl scan command. ```yaml theme={null} - run: name: "Endor Labs SAST Scan" command: | ./endorctl scan --sast --dependencies --secrets ``` ### AI SAST triage agent scan To run an AI SAST triage agent scan, add the `--sast` and `--ai-sast-analysis=agent-fallback` flags to your endorctl scan command. The AI SAST triage agent automatically classifies findings as true positives or false positives, reducing the need for manual triage. ```yaml theme={null} - run: name: "Endor Labs AI SAST Triage Scan" command: | ./endorctl scan --sast --ai-sast-analysis=agent-fallback --dependencies --secrets ``` To re-analyze all findings, including those that have already been analyzed, add the `--ai-sast-rescan` flag. ### AI SAST detection agent scan To run an AI SAST detection agent scan, add the `--ai-sast` flag to your endorctl scan command. The AI SAST detection agent identifies security vulnerabilities beyond traditional rule-based SAST detection. ```yaml theme={null} - run: name: "Endor Labs AI SAST Detection Scan" command: | ./endorctl scan --ai-sast --dependencies --secrets ``` ## Set up branch tracking in CircleCI In Git, a detached HEAD state occurs when the repository checks out a specific commit instead of a branch reference. In this state, Git points the HEAD directly to a commit hash, without associating it with a named branch. As a result, actions performed, such as creating new commits or running automated scans, do not carry branch identity unless explicitly specified. Proper branch context enables Endor Labs to: * Associate scans with the correct branch * Identify scans on the monitored default branch * Track findings and display metrics accurately across branches Without proper branch configuration, Endor Labs may create multiple branch entries for the same logical branch, leading to fragmented reporting and inaccurate metrics. Project with multiple branch entries CircleCI often checks out commits by their SHA instead of the branch name, which creates a detached HEAD state. Use `--detached-ref-name` only to specify the branch name for a commit in detached HEAD state. This associates the commit with the correct branch without setting it as the default branch. ```yaml theme={null} - run: name: "Endor Labs Scan" command: | ./endorctl scan --dependencies --secrets \ --detached-ref-name="<< pipeline.git.branch >>" ``` Use both `--detached-ref-name` and `--as-default-branch` together when you want to associate the commit with a branch and set it as the default branch scan. ```yaml theme={null} - run: name: "Endor Labs Scan" command: | ./endorctl scan --dependencies --secrets \ --as-default-branch \ --detached-ref-name="<< pipeline.git.branch >>" ``` # Scanning with GitHub Actions Source: https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-github-actions/index Learn how to implement Endor Labs in GitHub action workflows. GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can use GitHub Actions to include Endor Labs into your CI pipeline seamlessly. Using this pipeline, developers can view and detect: * Policy violations in the source code * Secrets inadvertently included in the source code The Endor Labs verifications are conducted as automated checks and help you discover violations before pushing code to the repository. Information about the violations can be included as comments on the corresponding pull request (PR). This enables developers to easily identify issues and take remedial measures early in the development life cycle. * For policy violations, the workflow is designed to either emit a warning or return an error based on your action policy configurations. * For secrets discovered in the commits, developers can view the PR comments and take necessary remedial measures. ## Install Software Prerequisites To ensure the successful execution of the Endor Labs GitHub action, the following prerequisites must be met: * The GitHub action must be able to authenticate with the Endor Labs API. * You must have the value of the Endor Labs namespace handy for authentication. * You must have access to the Endor Labs API. * If you use keyless authentication, you must set an authorization policy in Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies) for details. ## Secure GitHub Actions with immutable commit SHA Endor Labs recommends pinning the commit SHA of the GitHub Actions to enhance security. By pinning GitHub Actions to a commit SHA, you make the code immutable even if the tag version is changed or the code is updated. To manually find the Endor Labs GitHub action's latest commit SHA: 1. Go to [Endor Labs GitHub Actions](https://github.com/endorlabs/github-action) and select the latest release version in **Releases**. 2. Click the commit of the release. Select commit SHA of latest release 3. Copy the commit SHA from the URL. The commit SHA is the 40-character alphanumeric string in the URL after `/commit/`. Copy commit SHA ## Example GitHub Action Workflow Endor Labs scanning workflow using GitHub Actions that accomplishes the following tasks in your CI environment: * Tests PRs to the default branch and monitors the most recent push to the default branch. * Builds a Java project and sets up the Java build tools. If your project is not on Java, then configure this workflow with your project-specific steps and build tools. * Authenticates to Endor Labs with GitHub Actions keyless authentication. * Scan with Endor Labs. * Comments on PRs if any policy violations occur. * Generates findings and uploads results to GitHub in SARIF format. The following example workflow shows how to scan with Endor Labs for a Java application using the recommended keyless authentication for GitHub Actions. The examples pin the Endor Labs GitHub Action to release `v1.1.12`. To use a newer release, copy the **Use in your workflow** reference from **Latest GitHub Action Release** in [Secure GitHub Actions with immutable commit SHA](/setup-deployment/ci-cd/scan-with-github-actions#secure-github-actions-with-immutable-commit-sha). ```yaml expandable theme={null} name: Endor Labs Dependency and Secrets Scan on: push: branches: [ main ] pull_request: branches: [ main ] jobs: scan: permissions: security-events: write # Used to upload Sarif artifact to GitHub contents: read # Used to check out a private repository actions: read # Required for private repositories to upload Sarif files. GitHub Advanced Security licenses are required. id-token: write # Used for keyless authentication with Endor Labs pull-requests: write # Required to automatically comment on PRs for new policy violations runs-on: ubuntu-latest steps: - name: Checkout Repository uses: actions/checkout@v3 - name: Setup Java uses: actions/setup-java@v3 with: distribution: 'microsoft' java-version: '17' - name: Build Package run: mvn clean install - name: Endor Labs Scan Pull Request if: github.event_name == 'pull_request' uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' # Replace with your Endor Labs tenant namespace scan_dependencies: true scan_secrets: true pr: true enable_pr_comments: true # Required to automatically comment on PRs for new policy violations github_token: ${{ secrets.GITHUB_TOKEN }} # Required for PR comments on new policy violations scan-main: permissions: id-token: write repository-projects: read pull-requests: read contents: read name: endorctl-scan runs-on: ubuntu-latest steps: - name: Checkout Repository uses: actions/checkout@v3 - name: Setup Java uses: actions/setup-java@v3 with: distribution: 'microsoft' java-version: '17' - name: Build Package run: mvn clean install - name: 'Endor Labs Scan Push to main' if: ${{ github.event_name == 'push' }} uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' # Replace with your Endor Labs tenant namespace scan_dependencies: true scan_secrets: true pr: false scan_summary_output_type: 'table' sarif_file: 'findings.sarif' - name: Upload findings to github uses: github/codeql-action/upload-sarif@v3 with: sarif_file: 'findings.sarif' ``` A policy violation makes the scan exit with a non-zero code, which fails the job. Failing the job does not block a merge on its own. To block pull requests, mark the scan job as a required status check in GitHub. See [Block pull requests on findings](/scan/pr-scans#block-pull-requests-on-findings). ## Set up branch tracking in GitHub Actions In Git, a detached HEAD state occurs when the repository checks out a specific commit instead of a branch reference. In this state, Git points the HEAD directly to a commit hash, without associating it with a named branch. As a result, actions performed, such as creating new commits or running automated scans, do not carry branch identity unless explicitly specified. Proper branch context enables Endor Labs to: * Associate scans with the correct branch * Identify scans on the monitored default branch * Track findings and display metrics accurately across branches Without proper branch configuration, Endor Labs may create multiple branch entries for the same logical branch, leading to fragmented reporting and inaccurate metrics. Project with multiple branch entries GitHub Actions typically maintains proper branch context automatically. However, to ensure scans are properly tracked, when using the Endor Labs GitHub Action, set `pr: false` to create monitored versions that appear on dashboards. Use `if: github.event_name == 'push'` to trigger only on pushes to the default branch: ```yaml theme={null} - name: Endor Labs Scan Push to main if: github.event_name == 'push' uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' scan_dependencies: true pr: false ``` ## Scan containers with OS reachability You can use the Endor Labs GitHub Action to scan container images with [OS reachability](/scan/containers/container-reachability) enabled. Container reachability identifies which packages inside a container image are actually used at runtime, helping you prioritize the most critical vulnerabilities for remediation. Set `scan_container: true` and `os_reachability: true` to enable container scanning with reachability analysis: ```yaml theme={null} - name: Scan container with OS reachability uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' enable_github_action_token: 'true' scan_container: true scan_dependencies: false image: "nginx:latest" os_reachability: true pr: false project_name: 'my-project' ``` ## Authenticate with Endor Labs Endor Labs recommends using keyless authentication in CI environments. Keyless authentication is more secure and reduces the cost of secret rotation. To set up keyless authentication see [Keyless Authentication](/setup-deployment/ci-cd/keyless-authentication). If you choose not to use keyless authentication, you can configure an API key and secret in GitHub for authentication as outlined in [Managing API keys](/platform-administration/api-keys). ### Authentication Without Keyless Authentication for GitHub If you are not using keyless authentication for GitHub Actions, you must not provide `id-token: write` permissions to your GitHub token unless specifically required by a step in this job. You must also set `enable_github_action_token: false` in your Endor Labs GitHub Action configuration. The following example configuration uses the Endor Labs API key for authentication: ```yaml theme={null} - name: Scan with Endor Labs uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' api_key: ${{ secrets.ENDOR_API_CREDENTIALS_KEY }} api_secret: ${{ secrets.ENDOR_API_CREDENTIALS_SECRET }} enable_github_action_token: false ``` The following example configuration uses a GCP service account for keyless authentication to Endor Labs: ```yaml theme={null} - name: Scan with Endor Labs uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: 'example' gcp_service_account: '@.iam.gserviceaccount.com' enable_github_action_token: false ``` ## Configure for the EU cluster If you're an EU tenant, set the `ENDOR_API` environment variable to `https://api.eu.endorlabs.com` in your workflow and use an API key generated from your EU tenant at `https://app.eu.endorlabs.com`. Add an `env` block at the job level to apply the EU endpoint to all steps in the job: ```yaml theme={null} jobs: scan: runs-on: ubuntu-latest env: ENDOR_API: https://api.eu.endorlabs.com steps: - name: Checkout Repository uses: actions/checkout@v3 - name: Scan with Endor Labs uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12 with: namespace: '' api_key: ${{ secrets.ENDOR_API_CREDENTIALS_KEY }} api_secret: ${{ secrets.ENDOR_API_CREDENTIALS_SECRET }} enable_github_action_token: false scan_dependencies: true scan_secrets: true pr: false ``` Store your EU API credentials as secrets in your GitHub repository (for example, `ENDOR_API_CREDENTIALS_KEY` and `ENDOR_API_CREDENTIALS_SECRET`) and generate them from your EU tenant at `https://app.eu.endorlabs.com`. ## Endor Labs GitHub Action Configuration Parameters The following input configuration parameters are supported for the Endor Labs GitHub Action: ### Common parameters Endor Labs GitHub Actions supports the following input global parameters: ### Scanning parameters The following input parameters are also supported for the Endor Labs GitHub Action when used for scanning: **AI SAST scan options** * To enable an AI SAST triage agent scan, set the `additional_args` parameter to `--ai-sast-analysis=agent-fallback`. * To enable an AI SAST detection agent scan, set the `additional_args` parameter to `--ai-sast`. ### Environmental variables You can use the following environmental variable for the Endor Labs GitHub Action: ### Artifact scanning parameters Use the following parameters and the latest sign action to build artifact signing through Endor Labs GitHub Actions. The optional parameters are required only if `enable_github_action_token` in [common parameters](#common-parameters) is `false`. If `true` (default value), GitHub automatically populates the optional and other parameters as token claims and sends them to Endor Labs. ### Artifact verifying parameters Use the following verification parameters and the latest verify action to build artifact verification through Endor Labs GitHub Actions. # Scanning in GitLab Pipelines Source: https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-gitlab/index Learn how to implement Endor Labs across a GitLab CI pipeline. GitLab CI/CD pipelines are a part of GitLab's integrated continuous integration and deployment features. They allow you to define and automate the different stages and tasks in your software development workflow. This document provides an overview and example job to integrate Endor Labs into your GitLab CI pipeline. ## High Level Usage Steps 1. Setup authentication to Endor Labs 2. Install your build toolchain 3. Build your code 4. Scan with Endor Labs ### Authentication to Endor Labs Endor Labs recommends using keyless authentication in continuous integration environments. Keyless Authentication is more secure and reduces the cost of secret rotation. To set up keyless authentication see [the keyless authentication documentation](/setup-deployment/ci-cd/keyless-authentication) If you choose not to use keyless authentication you can configure an API key and secret in GitLab for authentication using the following steps. See [managing API keys for more information on getting an API key for Endor Labs authentication](/platform-administration/api-keys) ### Configure API key and secret in GitLab 1. In your GitLab environment, select the project you want to scan. 2. Go to **Settings** > **CI/CD**. 3. Click **Expand** in the Variables section. 4. Click the **Add variable** button at the bottom of the section. 5. In the **Key** field, enter **ENDOR\_API\_CREDENTIALS\_SECRET**. 6. In the **Value** field, enter your Endor Labs API secret. 7. Under **Flags**, make sure you select **Mask variable**. 8. Repeat the previous steps to add your API key as the variable **ENDOR\_API\_CREDENTIALS\_KEY**. ### Configure your GitLab CI pipeline **Important** GitLab CI/CD pipelines check out commits in a detached HEAD state, which can lead to fragmented branch tracking in Endor Labs. See [Set up branch tracking in GitLab](#set-up-branch-tracking-in-gitlab) to configure proper branch context. 1. Create a `.gitlab-ci.yml` file in the root directory of your project if you do not already have one. 2. In your `.gitlab-ci.yml` file customize the job configuration based on your project's requirements using the example below. 3. Modify the image field to align with the build tools necessary for building your software packages. 4. Update the before\_script section to include any additional steps required before executing the scan, such as installing dependencies or building your project. 5. Save and commit the `.gitlab-ci.yml` file to your GitLab repository. 6. GitLab will automatically detect the `.gitlab-ci.yml` file and trigger the defined job whenever there are changes pushed to the repository. 7. Monitor the progress and results of the CI pipeline in the GitLab CI/CD interface. You can use the following example job to get started. Make sure to customize this job with your specific build environment and build steps. ```yaml expandable theme={null} # You can copy and paste this template into a new `.gitlab-ci.yml` file. # You should not add this template to an existing `.gitlab-ci.yml` file by using the `include:` keyword. # stages: - Scan Endor Labs Dependency Scan: stage: test image: node # Modify this image to align with the build tools nessesary to build your software packages dependencies: [] variables: ## Scan scoping section # ## Use the following environment variables for custom paths, inclusions and exclusions. # ENDOR_SCAN_PATH: "Insert a custom path to your git repository. Defaults to your pwd" # ENDOR_SCAN_EXCLUDE_PATH: "Insert a Glob style pattern of paths to exclude in the scan. Generally used for monorepos." # ENDORCTL_SCAN_INCLUDE_PATH: "Insert a Glob style pattern of paths to include in the scan. Generally used for monorepos." # ## Authentication to Endor Labs # ## Use the following environment variables for keyless authentication with your cloud provider. For more information visit: https://docs.endorlabs.com/continuous-integration/keyless-authentication/ # # ENDOR_GCP_CREDENTIALS_SERVICE_ACCOUNT: "endorlabs@ `CI/CD`. ## Click `Expand` in the `Variables` section. ## Click the `Add variable` button at the bottom of the section. ## In the `Key` field, enter ENDOR_API_CREDENTIALS_SECRET. ## In the `Value` field, enter your Endor Labs API secret. ## Under `Flags` make sure you select `Mask variable`. ## Repeat to add your API key as the variable ENDOR_API_CREDENTIALS_KEY # ENDOR_ENABLED: "true" ENDOR_ALLOW_FAILURE: "false" ENDOR_NAMESPACE: "example" # Replace with your Endor Labs namespace ENDOR_PROJECT_DIR: "." ENDOR_ARGS: | --path=${ENDOR_PROJECT_DIR} --detached-ref-name=$CI_COMMIT_REF_NAME --output-type=summary --exit-on-policy-warning --dependencies --secrets --git-logs before_script: - npm install yarn # Replace with the build steps for your Endor Labs job. script: - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o ./endorctl; - echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) ./endorctl" | sha256sum -c; if [ $? -ne 0 ]; then echo "Integrity check failed"; exit 1; fi - chmod +x ./endorctl - if [ "$DEBUG" == "true" ]; then export ENDOR_LOG_VERBOSE=true; export ENDOR_LOG_LEVEL=debug; fi - if [ "$CI_COMMIT_REF_NAME" == "$CI_DEFAULT_BRANCH" ]; then export ENDOR_SCAN_AS_DEFAULT_BRANCH=true; export ENDOR_SCAN_DETACHED_REF_NAME="$CI_COMMIT_REF_NAME"; else export ENDOR_SCAN_PR=true; fi - ./endorctl scan ${ENDOR_ARGS} rules: - if: $ENDOR_ENABLED != "true" when: never - if: $ENDOR_ALLOW_FAILURE == "true" allow_failure: true - if: $ENDOR_ALLOW_FAILURE != "true" allow_failure: false ``` If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ## SAST scans in GitLab You can run SAST scans in your GitLab CI pipeline to identify security vulnerabilities and code quality issues in your source code. SAST scanning analyzes your source code for potential security weaknesses based on enabled rules and generates findings based on your configured finding policies. ### SAST scan To run a SAST scan, add `--sast` to your `ENDOR_ARGS` variable. ```yaml theme={null} variables: ENDOR_ARGS: | --path=${ENDOR_PROJECT_DIR} --sast --dependencies --secrets script: - ./endorctl scan ${ENDOR_ARGS} ``` ### AI SAST triage agent scan To run an AI SAST triage agent scan, add `--sast` and `--ai-sast-analysis=agent-fallback` to your `ENDOR_ARGS` variable. The AI SAST triage agent automatically classifies findings as true positives or false positives, reducing the need for manual triage. ```yaml theme={null} variables: ENDOR_ARGS: | --path=${ENDOR_PROJECT_DIR} --sast --ai-sast-analysis=agent-fallback --dependencies --secrets script: - ./endorctl scan ${ENDOR_ARGS} ``` To re-analyze all findings, including those that have already been analyzed, add `--ai-sast-rescan` to your `ENDOR_ARGS` variable. ### AI SAST detection agent scan To run an AI SAST detection agent scan, add `--ai-sast` to your `ENDOR_ARGS` variable. The AI SAST detection agent identifies security vulnerabilities beyond traditional rule-based SAST detection. ```yaml theme={null} variables: ENDOR_ARGS: | --path=${ENDOR_PROJECT_DIR} --ai-sast --dependencies --secrets script: - ./endorctl scan ${ENDOR_ARGS} ``` ### AI SAST MR scan To run an AI SAST MR scan, add `--ai-sast`, `--pr`, and `--pr-baseline` to your `ENDOR_ARGS` variable. The scan analyzes only the code changed by the merge request and surfaces the net new findings introduced by the change. A baseline AI SAST scan must exist on the target branch first. See [AI SAST PR scans](/scan/ai-sast/ai-sast-pr-scans) to learn more. ```yaml theme={null} variables: ENDOR_ARGS: | --path=${ENDOR_PROJECT_DIR} --ai-sast --pr --pr-baseline=main script: - ./endorctl scan ${ENDOR_ARGS} ``` ## Set up branch tracking in GitLab In Git, a detached HEAD state occurs when the repository checks out a specific commit instead of a branch reference. In this state, Git points the HEAD directly to a commit hash, without associating it with a named branch. As a result, actions performed, such as creating new commits or running automated scans, do not carry branch identity unless explicitly specified. Proper branch context enables Endor Labs to: * Associate scans with the correct branch * Identify scans on the monitored default branch * Track findings and display metrics accurately across branches Without proper branch configuration, Endor Labs may create multiple branch entries for the same logical branch, leading to fragmented reporting and inaccurate metrics. Project with multiple branch entries GitLab CI/CD checks out commits by their SHA instead of the branch name, which creates a detached HEAD state. Use `--detached-ref-name` only to specify the branch name for a commit in detached HEAD state. This associates the commit with the correct branch without setting it as the default branch. ```yaml theme={null} variables: ENDOR_ARGS: | --path=${ENDOR_PROJECT_DIR} --detached-ref-name=$CI_COMMIT_REF_NAME --dependencies --secrets script: - ./endorctl scan ${ENDOR_ARGS} ``` Use both `--detached-ref-name` and `--as-default-branch` together when you want to associate the commit with a branch and set it as the default branch scan. ```yaml theme={null} variables: ENDOR_ARGS: | --path=${ENDOR_PROJECT_DIR} --detached-ref-name=$CI_COMMIT_REF_NAME --dependencies --secrets script: - if [ "$CI_COMMIT_REF_NAME" == "$CI_DEFAULT_BRANCH" ]; then export ENDOR_SCAN_AS_DEFAULT_BRANCH=true; else export ENDOR_SCAN_PR=true; fi - ./endorctl scan ${ENDOR_ARGS} ``` ## Run MR scans MR scans are point-in-time scans that run on merge requests to detect new policy violations and security issues introduced by the changes. Unlike default branch scans which create monitored versions, MR scans compare findings against the baseline to surface only new issues. To run scans on merge requests, use the `--pr` flag. This flag tells endorctl to treat the scan as a merge request scan and compare findings against the target branch baseline. The following example configuration runs an MR scan only when triggered by a merge request pipeline: ```yaml expandable theme={null} Endor Labs MR Scan: stage: test image: node variables: ENDOR_NAMESPACE: "example" # Replace with your Endor Labs namespace ENDOR_PROJECT_DIR: "." ENDOR_ARGS: | --path=${ENDOR_PROJECT_DIR} --detached-ref-name=$CI_COMMIT_REF_NAME --pr --dependencies --secrets before_script: - npm install # Replace with your build steps script: - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o ./endorctl - echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) ./endorctl" | sha256sum -c - chmod +x ./endorctl - ./endorctl scan ${ENDOR_ARGS} rules: - if: $CI_MERGE_REQUEST_IID ``` The `--detached-ref-name` flag is recommended for MR scans in GitLab because merge request pipelines check out commits in a detached HEAD state. This flag provides the branch name context needed for proper baseline comparison. ## Enable MR comments You can enable MR comments in your GitLab CI pipeline to automatically post comments on merge requests when policy violations are detected. MR comments build on top of [MR scans](#run-mr-scans) by posting the scan results directly on the merge request. **Configure a GitLab token** Configure a GitLab CI/CD variable following the same steps as described in [Configure API key and secret in GitLab](#configure-api-key-and-secret-in-gitlab). Add a variable with the key `ENDOR_SCAN_SCM_TOKEN` and set its value to your GitLab personal access token with the `api` scope. Make sure to select **Mask variable** under Flags. ### Configure the pipeline for MR comments The following example configuration enables MR comments in your GitLab CI pipeline: ```yaml expandable theme={null} Endor Labs MR Scan: stage: test image: node variables: ENDOR_NAMESPACE: "example" # Replace with your Endor Labs namespace ENDOR_PROJECT_DIR: "." ENDOR_ARGS: | --path=${ENDOR_PROJECT_DIR} --detached-ref-name=$CI_COMMIT_REF_NAME --pr --enable-pr-comments --scm-pr-id=$CI_MERGE_REQUEST_IID --scm-token=$ENDOR_SCAN_SCM_TOKEN --dependencies --secrets before_script: - npm install # Replace with your build steps script: - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o ./endorctl - echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) ./endorctl" | sha256sum -c - chmod +x ./endorctl - ./endorctl scan ${ENDOR_ARGS} rules: - if: $CI_MERGE_REQUEST_IID ``` The key flags for MR comments are: * `--pr`: Enables MR scan mode * `--enable-pr-comments`: Enables posting comments on the merge request * `--scm-pr-id=$CI_MERGE_REQUEST_IID`: Provides the merge request ID * `--scm-token=$ENDOR_SCAN_SCM_TOKEN`: Provides the GitLab token for posting comments ### Configure an action policy After you enable MR comments, you need to set up an action policy to allow comments to be posted on merge requests. See [Configure Action policy for PR comments](/scan/pr-scans/pr-comments#configure-action-policy-for-pr-comments) for more information. # Scanning with Google Cloud Build Source: https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-google-cloud-build/index Learn how to implement Endor Labs with Google Cloud Build. Google Cloud Build is a fully managed continuous integration and continuous delivery (CI/CD) service offered by Google Cloud Platform. To integrate Endor Labs with Google Cloud Build: * [Authenticate to Endor Labs](#authenticate-to-endor-labs) * [Set up Google Cloud prerequisites](#set-up-google-cloud-prerequisites) * [Set up repositories on Google Cloud Build](#set-up-repositories-on-google-cloud-build) * [Create Cloud Build triggers](#create-cloud-build-triggers) * [Baseline scan](#baseline-scan) * [PR scan](#pr-scan) * [Release scan](#release-scan) * [Example configuration file](#example-configuration-file) ## Authenticate to Endor Labs Generate API credentials to authenticate to Endor Labs. Configure the API key and secret in the `cloudbuild.yaml` file for authentication. See [managing API keys](/platform-administration/api-keys) for more information on generating an API key for Endor Labs. You can enable keyless authentication to Google Cloud. See [Keyless authentication in Google Cloud](/setup-deployment/ci-cd/keyless-authentication/google-keyless-auth) for more information. ## Set up Google Cloud prerequisites Ensure the following prerequisites are in place in Google Cloud Build before integrating with Endor Labs. * **GCP Service Account**: Create a service account to operate Google Cloud Build. * **APIs**: * Enable the Google Cloud Build API. * Enable the Secrets Manager API. * **Secrets**: * Create secrets in Secret Manager to store the Endor Labs API credentials: `endor-api-key` and `endor-api-secret`. * **Permissions**: Grant the service account the following roles: * **Secret Manager Secret Accessor**: Allows the service account to access API credentials from Secret Manager. * **Logging Admin**: Allows the service account to write build logs to Cloud Logging. ## Set up repositories on Google Cloud Build 1. Sign in to the Google Cloud Build console. 2. Navigate to Repositories. 3. Follow the instructions in [Connecting GitHub Repositories to Cloud Build](https://cloud.google.com/build/docs/automating-builds/github/connect-repo-github?generation=2nd-gen) to add the repositories you want to scan with Cloud Build. ## Create Cloud Build triggers **Important** Google Cloud Build may check out commits in a detached HEAD state, which can lead to fragmented branch tracking in Endor Labs. See [Set up branch tracking in Google Cloud Build](#set-up-branch-tracking-in-google-cloud-build) to configure proper branch context. Triggers initiate Cloud Build for different types of scans. You can set up triggers for the following scan types: * [Baseline scan](#baseline-scan) * [PR scan](#pr-scan) * [Release scan](#release-scan) ### Baseline scan * **Purpose**: Scans the baseline or the default branch to identify existing security vulnerabilities. Future code and dependencies will be evaluated against this baseline. * **Trigger Type**: Push to branch. * **Setup**: Create a trigger for the required repository and branch, for example, main, or develop. * **Cloud Build Configuration**: Create a `cloudbuild.yaml` file using the [configuration file examples](#example-configuration-file) as a reference. Include this file for baseline scans in the required GitHub repository. ### PR scan * **Purpose**: Scans the pull requests that could include new code and dependencies for vulnerabilities and security risks. This scan compares the new code against the baseline or the default branch and raises results based on findings and admission policies. * **Trigger Type**: Pull request. * **Setup**: Create a trigger for the required repository and branch. * **Additional Parameters**: Pass extra parameters as part of the endorctl arguments. * **Cloud Build Configuration**: Create a `cloudbuild.yaml` file using the [configuration file examples](#example-configuration-file) as a reference. Include this file for baseline scans in the required GitHub repository, ### Release scan * **Purpose**: Scans code before it lands in production or pre-production environments. This is similar to a baseline scan, however, it is triggered when you push the code to a release branch or create a new release tag. * **Trigger Type**: Push to branch or push to new tag. * **Setup**: Create a trigger for the release branch or tag. * **Cloud Build Configuration**: Create a `cloudbuild.yaml` file using the [configuration file examples](#example-configuration-file) excluding the `--as-default-branch argument` for release scans, and add this file to the required GitHub repository. ### Example configuration file Here is an example `cloudbuild.yaml` configuration file to perform a baseline scan for Java project repository. If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`. ```bash expandable theme={null} steps: # Step 1: Fetch The Trigger Branch # This step addresses a known issue where Cloud Build renames the pulled branch to main. # If you are not encountering this issue with your build, you can skip this step. - name: 'gcr.io/cloud-builders/git' entrypoint: 'bash' args: - '-c' - | echo "Fetching all branches..." git fetch origin echo "Checking out branch: ${BRANCH_NAME}" git checkout ${BRANCH_NAME} # Step 2: Build With Maven - name: 'maven:3.8.6-openjdk-11' entrypoint: 'mvn' args: ['clean', 'install'] id: 'Build' # Step 3: Install latest version of endorctl - name: 'maven:3.8.6-openjdk-11' entrypoint: 'bash' args: - '-c' - | curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c chmod +x ./endorctl ./endorctl --version id: 'Install latest version of endorctl' # Step 4: SCA Scan With EndorLabs - name: 'maven:3.8.6-openjdk-11' entrypoint: 'bash' args: ["-c", "./endorctl scan -n $$ENDOR_NAMESPACE --api-key=$$ENDOR_API_CREDENTIALS_KEY --api-secret=$$ENDOR_API_CREDENTIALS_SECRET --as-default-branch=true"] secretEnv: ['ENDOR_API_CREDENTIALS_KEY', 'ENDOR_API_CREDENTIALS_SECRET'] env: - 'ENDOR_NAMESPACE=demo' id: 'SCA Scan With EndorLabs' # Fetch Endor Labs API Token and Secret From Secrets Manager availableSecrets: secretManager: - versionName: projects/{your-project-id}/secrets/endor-api-key/versions/1 env: 'ENDOR_API_CREDENTIALS_KEY' - versionName: projects/{your-project-id}/secrets/endor-api-secret/versions/1 env: 'ENDOR_API_CREDENTIALS_SECRET' options: # Choose your log configuration logging: 'CLOUD_LOGGING_ONLY' # Select a private pool if the default runners do not meet the minimum requirements. pool: name: 'projects/{your-project-id}/locations/{your_location}/workerPools/{your_worker_pool_id}' ``` Check the example [configuration files](https://github.com/Endor-Solutions-Architecture/CI-CD-Examples/tree/main/gcp_cloud_build) and customize them for your requirements. ## SAST scans in Google Cloud Build You can run SAST scans in your Google Cloud Build pipeline to identify security vulnerabilities and code quality issues in your source code. SAST scanning analyzes your source code for potential security weaknesses based on enabled rules and generates findings based on your configured finding policies. ### SAST scan To run a SAST scan, add the `--sast` flag to your endorctl scan command. For example: ```yaml theme={null} - name: 'maven:3.8.6-openjdk-11' entrypoint: 'bash' args: ["-c", "./endorctl scan -n $$ENDOR_NAMESPACE --sast --api-key=$$ENDOR_API_CREDENTIALS_KEY --api-secret=$$ENDOR_API_CREDENTIALS_SECRET"] ``` ### AI SAST triage agent scan To run an AI SAST triage agent scan, add the `--sast` and `--ai-sast-analysis=agent-fallback` flags to your endorctl scan command. The AI SAST triage agent automatically classifies findings as true positives or false positives, reducing the need for manual triage. For example: ```yaml theme={null} - name: 'maven:3.8.6-openjdk-11' entrypoint: 'bash' args: ["-c", "./endorctl scan -n $$ENDOR_NAMESPACE --sast --ai-sast-analysis=agent-fallback --api-key=$$ENDOR_API_CREDENTIALS_KEY --api-secret=$$ENDOR_API_CREDENTIALS_SECRET"] ``` To re-analyze all findings, including those that have already been analyzed, add the `--ai-sast-rescan` flag. ### AI SAST detection agent scan To run an AI SAST detection agent scan, add the `--ai-sast` flag to your endorctl scan command. The AI SAST detection agent identifies security vulnerabilities beyond traditional rule-based SAST detection. ```yaml theme={null} - name: 'maven:3.8.6-openjdk-11' entrypoint: 'bash' args: ["-c", "./endorctl scan -n $$ENDOR_NAMESPACE --ai-sast --api-key=$$ENDOR_API_CREDENTIALS_KEY --api-secret=$$ENDOR_API_CREDENTIALS_SECRET"] ``` ## Set up branch tracking in Google Cloud Build In Git, a detached HEAD state occurs when the repository checks out a specific commit instead of a branch reference. In this state, Git points the HEAD directly to a commit hash, without associating it with a named branch. As a result, actions performed, such as creating new commits or running automated scans, do not carry branch identity unless explicitly specified. Proper branch context enables Endor Labs to: * Associate scans with the correct branch * Identify scans on the monitored default branch * Track findings and display metrics accurately across branches Without proper branch configuration, Endor Labs may create multiple branch entries for the same logical branch, leading to fragmented reporting and inaccurate metrics. Project with multiple branch entries Google Cloud Build often checks out commits by their SHA instead of the branch name, which creates a detached HEAD state. Use `--detached-ref-name` only to specify the branch name for a commit in detached HEAD state. This associates the commit with the correct branch without setting it as the default branch. ```yaml theme={null} - name: 'gcr.io/cloud-builders/docker' entrypoint: 'bash' args: - '-c' - | endorctl scan --dependencies \ --detached-ref-name="${BRANCH_NAME}" ``` Use both `--detached-ref-name` and `--as-default-branch` together when you want to associate the commit with a branch and set it as the default branch scan. ```yaml theme={null} - name: 'gcr.io/cloud-builders/docker' entrypoint: 'bash' args: - '-c' - | endorctl scan --dependencies \ --as-default-branch \ --detached-ref-name="${BRANCH_NAME}" ``` # Scanning with Jenkins Source: https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-jenkins/index Learn how to implement Endor Labs in a Jenkins pipeline. Jenkins is an open-source automation server widely used for building, testing, and deploying software. Specifically in the context of CI/CD pipelines, Jenkins serves as a powerful tool to automate multiple stages of the software development lifecycle. To integrate Endor Labs into your Jenkins CI/CD processes: 1. [Authenticate to Endor Labs](#authenticate-to-endor-labs) 2. Install NodeJS plugin in Jenkins. 3. Install your build toolchain 4. Build your code 5. Scan with Endor Labs **EU tenants:** Add `ENDOR_API` as an environment variable set to `https://api.eu.endorlabs.com` in your Jenkins credentials context, alongside your other Endor Labs credentials. Use an API key generated from your EU tenant at `https://app.eu.endorlabs.com`. ## Authenticate to Endor Labs To configure keyless authentication see [the keyless authentication documentation](/setup-deployment/ci-cd/keyless-authentication). If you choose not to use keyless authentication you can configure an API key and secret in Jenkins for authentication using the following steps. See [managing API keys](/platform-administration/api-keys) for more information on generating an API key for Endor Labs. 1. In your Jenkins environment, navigate to **Manage Jenkins**. 2. Enter a credential name for reference such as `endorlabs` or reuse an existing context. 3. Click into your new or existing context. Add any project restrictions and select **Add Environment Variable**. 4. In **Environment Variable Name**, enter **ENDOR\_API\_CREDENTIALS\_KEY** and in **Value**, enter the Endor Labs API Key. 5. Select **Add Environment Variable**. ## Install Node.js plugin in Jenkins See [Jenkins documentation](https://plugins.jenkins.io/nodejs/) to install Node.js plugin in Jenkins. You must have the Node.js plugin to use npm and download endorctl. ## Configure your Jenkins pipeline **Important** Jenkins often checks out commits in a detached HEAD state, which can lead to fragmented branch tracking in Endor Labs. See [Set up branch tracking in Jenkins](#set-up-branch-tracking-in-jenkins) to configure proper branch context. To create a Jenkins pipeline: 1. Create a configuration pipeline file in your repository if you do not already have one using the pipeline project. 2. In your configuration pipeline file customize the job configuration based on your project's requirements using one of the examples, [simple Jenkins configuration](#simple-jenkins-configuration-using-npm) or [Jenkins pipeline using curl](#jenkins-pipe-line-for-curl-to-download-endorctl-binary). 3. Ensure that the context you created is part of the workflow if you are not using keyless authentication. 4. Adjust the image field to conform to the required build tools for constructing your software packages, and synchronize your build steps with those of your project. 5. Update your Endor Labs tenant namespace to the appropriate namespace for your project. 6. Update your default branch from main if you do not use main as the default branch name. 7. Modify any dependency or artifact caches to align with the languages and caches used by your project. ## Examples Use the following examples to get started. Make sure to customize this job with your specific build environment and build steps. ### Simple Jenkins configuration using npm ```bash expandable theme={null} pipeline { agent any tools {nodejs "NodeJS"} environment { ENDOR_API = credentials('ENDOR_API') ENDOR_NAMESPACE = credentials('ENDOR_NAMESPACE') ENDOR_API_CREDENTIALS_KEY = credentials('ENDOR_API_CREDENTIALS_KEY_1') ENDOR_API_CREDENTIALS_SECRET = credentials('ENDOR_API_CREDENTIALS_SECRET_1') } stages { stage('Checkout') { steps { // Checkout the Git repository checkout scmGit(branches: [[name: '*/main']], userRemoteConfigs: [[url: 'https://github.com/endorlabstest/app-java-demo.git']]) } } stage('Build') { steps { // Perform any build steps if required sh 'mvn clean install' } } stage('endorctl Scan') { steps { script { // Define the Node.js installation name configured in Jenkins NODEJS_HOME = tool name: 'NodeJS', type: 'jenkins.plugins.nodejs.tools.NodeJSInstallation' PATH = "$NODEJS_HOME/bin:${env.PATH}" } // Download and install endorctl. sh 'npm install -g endorctl' // Check endorctl version and installation. sh 'endorctl --version' // Run the scan. sh('endorctl scan -a $ENDOR_API -n $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET') } } stage('Results') { steps { // Publish or process the vulnerability scan results // Publish reports, fail the build on vulnerabilities, etc. echo 'Publish results' } } } } ``` ### Jenkins pipe line for curl to download endorctl binary The following example includes curl to download the endorctl binary. ```bash expandable theme={null} pipeline { agent any // Endorctl scan uses following environment variables to the trigger endorctl scan environment { ENDOR_API = credentials('ENDOR_API') ENDOR_NAMESPACE = credentials('ENDOR_NAMESPACE') ENDOR_API_CREDENTIALS_KEY = credentials('ENDOR_API_CREDENTIALS_KEY') ENDOR_API_CREDENTIALS_SECRET = credentials('ENDOR_API_CREDENTIALS_SECRET') } stages { // Not required if repository is allready cloned to trigger a endorctl scan stage('Checkout') { steps { // Checkout the Git repository checkout scmGit(branches: [[name: '*/main']], userRemoteConfigs: [[url: 'https://github.com/endorlabstest/app-java-demo.git']]) } } stage('Build') { // Not required if project is already built steps { // Perform any build steps if required sh 'mvn clean install' } } stage('endorctl Scan') { steps { // Download and install endorctl. sh '''#!/bin/bash echo "Downloading latest version of endorctl" VERSION=$(curl $ENDOR_API/meta/version | jq -r '.ClientVersion') ENDORCTL_SHA=$(curl $ENDOR_API/meta/version | jq -r '.ClientChecksums.ARCH_TYPE_LINUX_AMD64') curl $ENDOR_API/download/endorlabs/"$VERSION"/binaries/endorctl_"$VERSION"_linux_amd64 -o endorctl echo "$ENDORCTL_SHA endorctl" | sha256sum -c if [ $? -ne 0 ]; then echo "Integrity check failed" exit 1 fi chmod +x ./endorctl // Check endorctl version and installation. ./endorctl --version // Run the scan. ./endorctl scan -a $ENDOR_API -n $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET ''' } } } } ``` Once you've set up Endor Labs you can test your CI implementation is successful and begin scanning. ## SAST scans in Jenkins You can run SAST scans in your Jenkins pipeline to identify security vulnerabilities and code quality issues in your source code. SAST scanning analyzes your source code for potential security weaknesses based on enabled rules and generates findings based on your configured finding policies. ### SAST scan To run a SAST scan, add the `--sast` flag to your endorctl scan command. ```bash theme={null} sh('endorctl scan -a $ENDOR_API -n $ENDOR_NAMESPACE --sast \ --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET') ``` ### AI SAST triage agent scan To run an AI SAST triage agent scan, add the `--sast` and `--ai-sast-analysis=agent-fallback` flags to your endorctl scan command. The AI SAST triage agent automatically classifies findings as true positives or false positives, reducing the need for manual triage. ```bash theme={null} sh('endorctl scan -a $ENDOR_API -n $ENDOR_NAMESPACE --sast --ai-sast-analysis=agent-fallback \ --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET') ``` To re-analyze all findings, including those that have already been analyzed, add the `--ai-sast-rescan` flag. ### AI SAST detection agent scan To run an AI SAST detection agent scan, add the `--ai-sast` flag to your endorctl scan command. The AI SAST detection agent identifies security vulnerabilities beyond traditional rule-based SAST detection. ```bash theme={null} sh('endorctl scan -a $ENDOR_API -n $ENDOR_NAMESPACE --ai-sast \ --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET') ``` ## Set up branch tracking in Jenkins In Git, a detached HEAD state occurs when the repository checks out a specific commit instead of a branch reference. In this state, Git points the HEAD directly to a commit hash, without associating it with a named branch. As a result, actions performed, such as creating new commits or running automated scans, do not carry branch identity unless explicitly specified. Proper branch context enables Endor Labs to: * Associate scans with the correct branch * Identify scans on the monitored default branch * Track findings and display metrics accurately across branches Without proper branch configuration, Endor Labs may create multiple branch entries for the same logical branch, leading to fragmented reporting and inaccurate metrics. Project with multiple branch entries Jenkins often checks out commits by their SHA instead of the branch name, which creates a detached HEAD state. Use `--detached-ref-name` only to specify the branch name for a commit in detached HEAD state. This associates the commit with the correct branch without setting it as the default branch. ```bash theme={null} sh('endorctl scan -a $ENDOR_API -n $ENDOR_NAMESPACE \ --detached-ref-name="${BRANCH_NAME}" \ --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET') ``` Use both `--detached-ref-name` and `--as-default-branch` together when you want to associate the commit with a branch and set it as the default branch scan. ```bash theme={null} sh('endorctl scan -a $ENDOR_API -n $ENDOR_NAMESPACE \ --as-default-branch \ --detached-ref-name="${BRANCH_NAME}" \ --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET') ``` # endorctl CLI Source: https://docs.endorlabs.com/setup-deployment/cli/index Install, configure, and authenticate with the Endor Labs command-line interface. Perform software composition analysis, dependency management, or detect secrets in your code using Endor Labs. ## Download and install endorctl Use one of the following methods to download and install endorctl on your local system. After you install endorctl, you must authenticate. Then you can start scanning your code. ### Install endorctl with Homebrew Use Homebrew to efficiently install endorctl on macOS and Linux operating systems making it easy to manage dependencies, and track installed packages with their versions. Install endorctl from the [Endor Labs tap](https://github.com/endorlabs/homebrew-tap) with Homebrew by running the following commands. The tap is updated regularly with the latest endorctl release. ```bash theme={null} brew install endorlabs/tap/endorctl ``` ### Install endorctl with npm Use npm to efficiently install endorctl on macOS, Linux, and Windows operating systems making it easy to manage dependencies, track and update installed packages and their versions. 1. Make sure that you have npm installed in your local environment and use the following command to install endorctl. ```bash theme={null} npm install -g endorctl ``` 2. Run the following command to get the npm global bin directory. ```bash theme={null} npm config get prefix ``` 3. Edit your shell configuration file and insert the path you obtained from the previous command. ```bash theme={null} export PATH="/path/to/npm/global/bin:$PATH" ``` 4. Reload your shell configuration and verify endorctl is installed. ```bash theme={null} endorctl --version ``` 5. To update your version of endorctl, run the following command. ```bash theme={null} npm update -g endorctl ``` [endorctl](https://www.npmjs.com/package/endorctl) is available as an npm package and is updated regularly with the latest endorctl release. ### Download and install the endorctl binary directly To download the endorctl binary directly use the following commands: ```bash theme={null} ## Download the latest CLI for Linux amd64 curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl ## Verify the checksum of the binary echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64) endorctl" | sha256sum -c ## Modify the permissions of the binary to ensure it is executable chmod +x ./endorctl ## Create an alias endorctl of the binary to ensure it is available in other directory alias endorctl="$PWD/endorctl" ``` ```bash theme={null} ### Download the latest CLI for MacOS ARM64 curl https://api.endorlabs.com/download/latest/endorctl_macos_arm64 -o endorctl ### Verify the checksum of the binary echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_macos_arm64) endorctl" | shasum -a 256 -c ### Modify the permissions of the binary to ensure it is executable chmod +x ./endorctl ### Create an alias endorctl of the binary to ensure it is available in other directory alias endorctl="$PWD/endorctl" ``` ```bash theme={null} ## Download the latest CLI for Windows amd64 curl -O https://api.endorlabs.com/download/latest/endorctl_windows_amd64.exe ## Check the expected checksum of the binary file curl https://api.endorlabs.com/sha/latest/endorctl_windows_amd64.exe ## Verify the expected checksum and the actual checksum of the binary match certutil -hashfile .\endorctl_windows_amd64.exe SHA256 ## Rename the binary file ren endorctl_windows_amd64.exe endorctl.exe ``` **EU Setup** If you're using a EU tenant, use `https://api.eu.endorlabs.com` as the API endpoint. You can also view these instructions via the Endor Labs application user interface: 1. Select **Projects** from the left sidebar. 2. Click **Add Project**. 3. Choose **CLI**. 4. Follow the on-screen instructions to download and install the appropriate version and architecture of `endorctl` for your system. ## Authenticate to Endor Labs You can authenticate to Endor Labs in multiple ways: 1. [Using the init command](#login-with-the-init-command) 2. [With an API token](#login-with-an-api-key) ### Login with the init command To log in with your supported authentication provider: ```bash theme={null} endorctl init --auth-mode=google ``` ```bash theme={null} endorctl init --auth-mode=github ``` ```bash theme={null} endorctl init --auth-mode=gitlab ``` ```bash theme={null} endorctl init --auth-email= ``` ```bash theme={null} endorctl init --auth-mode=sso --auth-tenant= ``` To log in with your supported authentication provider in environments without a browser you can use headless mode: ```bash theme={null} endorctl init --auth-mode=google --headless-mode ``` ```bash theme={null} endorctl init --auth-mode=github --headless-mode ``` ```bash theme={null} endorctl init --auth-mode=gitlab --headless-mode ``` ```bash theme={null} endorctl init --auth-email= --headless-mode ``` ```bash theme={null} endorctl init --auth-mode=sso --auth-tenant= --headless-mode ``` ### Login with an API Key To log in with an API key you'll need to set the following environment variables: * **ENDOR\_API\_CREDENTIALS\_KEY** - The API key used to authenticate against the Endor Labs API. * **ENDOR\_API\_CREDENTIALS\_SECRET** - The API key secret used to authenticate against the Endor Labs API. * **ENDOR\_NAMESPACE** - The Endor Labs namespace you would like to scan against. You can locate the namespace from the top left hand corner of the screen under the Endor Labs logo on the [Endor Labs application](https://app.endorlabs.com). If you use Endor Labs with an EU tenant, use `https://app.eu.endorlabs.com` instead of `https://app.endorlabs.com`. To get an API Key and secret for use with endorctl, see [Managing API Keys](/platform-administration/api-keys). To set your environment variables run the following commands and replace each example with the appropriate value. ```bash theme={null} export ENDOR_API_CREDENTIALS_KEY= export ENDOR_API_CREDENTIALS_SECRET= export ENDOR_NAMESPACE= ``` Once you've exported your environment variables you can test successful authentication by running the following command to list projects in your namespace. ```bash theme={null} endorctl api list -r Project --page-size=1 ``` If you do not have any projects in your namespace you will get an empty json output, which means you are successfully authenticated. ### Print your access token Once you have successfully initialized endorctl, you can print your access token with the following command. ```bash theme={null} endorctl auth --print-access-token ``` The token has an expiration time of 4 hours. ## Clone your repository Upon successful authentication to Endor Labs using `endorctl`, proceed to clone the repository you intend to scan. If you prefer initiating with a dummy app for scanning, feel free to skip to the next step. To clone a Git repository, use the `git clone` command followed by the clone link of the repository. You can find the URL on the repository's page on a platform like GitHub or GitLab. For example, ```bash theme={null} git clone https://github.com/username/repo-name.git ``` Replace `https://github.com/username/repo-name.git` with the actual URL of the Git repository you want to clone. Navigate to the repository you've cloned. ```bash theme={null} cd ``` ## Software prerequisites for endorctl scan The following prerequisites must be met to scan with Endor Labs: * A local installation of Git or the ability to clone repositories in CI. See the [Git documentation for instructions on installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) * A runtime environment and build tools for supported software development languages your team uses must be installed on any system used for testing. For more information, see [Supported languages and frameworks](/scan/sca). For more information, see [endorctl commands](/developers-api/cli/commands) and [working with the API](/developers-api/cli/commands/api). ## Build your software To run a complete and accurate scan with Endor Labs, ensure that the software can be successfully built, incorporating well-formatted manifest files. To maximize the benefits of an Endor Labs OSS scan, you should perform a comprehensive testing as a post-build step, either locally or in a CI pipeline. Use the following commands to verify that the software can be built successfully with well-formatted manifest files before initiating the scan. ```bash theme={null} mvn dependency:tree mvn clean install ``` ```bash theme={null} gradle dependencies --configuration runtimeClasspath ./gradlew assemble # Use `gradle assemble` if you do not have a gradle wrapper in your repository ``` ```bash theme={null} npm install ``` ```bash theme={null} yarn install ``` ```bash theme={null} export ENDOR_PNPM_ENABLED=true pnpm install ``` ```bash theme={null} export ENDOR_RUSH_ENABLED=true rush install ``` ```bash theme={null} dotnet restore dotnet build ``` ```bash theme={null} composer install ``` ```bash theme={null} go mod tidy ``` ```bash theme={null} python3 -m venv venv source venv/bin/activate venv/bin/python3 -m pip install ``` ```bash theme={null} poetry install ``` ```bash theme={null} bundler install ``` ```bash theme={null} pod install ``` ```bash theme={null} sbt projects sbt compile sbt dependencyTree ``` ```bash theme={null} gradle dependencies --configuration runtimeClasspath ./gradlew assemble # Use `gradle assemble` if you do not have a gradle wrapper in your repository ``` ```bash theme={null} cargo build ``` ## Persistently set environment variables for endorctl To persistently set an environment variable, append the environment variable and the value to `~/.endorctl/config.yaml`. This configuration file is for CLI usage. For example, if your GitHub Enterprise Server URL was [https://api.github.com](https://api.github.com) you can set the variable to persist in your configuration using the following command. ```bash theme={null} echo "ENDOR_SCAN_SOURCE_GITHUB_API_URL: https://api.github.com" >> ~/.endorctl/config.yaml ``` See [endorctl commands for all supported commands and environment variables](/developers-api/cli/environment-variables). # Scan using endorctl Source: https://docs.endorlabs.com/setup-deployment/cli/scan-using-endorctl/index Scan for open source risk, SAST findings, leaked secrets, and GitHub misconfigurations using endorctl. Use endorctl to perform comprehensive security analysis across your codebase, enabling you to detect dependency vulnerabilities, identify insecure code patterns, uncover exposed secrets, and evaluate GitHub configuration against best practices. To run your first scan with Endor Labs, complete the following steps: 1. [Install Endor Labs on your local system](/setup-deployment/cli#download-and-install-endorctl) 2. [Authenticate to Endor Labs](/setup-deployment/cli#authenticate-to-endor-labs) 3. [Clone your repository](/setup-deployment/cli#clone-your-repository) 4. [Scan your first project](#run-your-first-scan) ## Run your first scan Endor Labs supports four distinct scan types to identify open source risk, code issues, leaked secrets, and configuration gaps. * [Scan for OSS risk](#scan-for-oss-risk) * [Scan for SAST](#scan-for-sast) * [Scan for leaked secrets](#scanning-for-leaked-secrets) * [Scan for GitHub misconfigurations](#scan-for-github-misconfigurations) **Default namespace and access** When you run a scan, you can specify a [namespace](/developers-api/cli/environment-variables#global-flags-and-variables). If you leave it unspecified, projects are created in the root namespace of the tenant. That matters when your account or token only has access to specific namespaces. See [Namespaces in Endor Labs](/platform-administration/namespaces) for details. ### Scan for OSS risk To scan and monitor all packages in a given repository from the root of the repository, run the following command: ```bash theme={null} endorctl scan ``` If your project contains multiple programming languages, you can specify them as a comma-separated list using the `--languages` flag: ```bash theme={null} endorctl scan --languages= ``` Where `` should be provided as a comma-separated list from the supported languages: . #### Scan projects with private Git dependencies If your project depends on private Git repositories, Endor Labs reuses credentials from existing SCM integrations in your namespace to resolve them. Dependency resolution may fail when the scan environment cannot access a repository. To resolve this, provide host URLs and access tokens for those repositories before you run the CLI scan. You can configure credentials for multiple repositories across the same or different SCM platforms. Ensure that your access tokens have the required permissions. See [Supported SCM platforms and access tokens](/integrations/package-managers/git-based-dependencies#supported-scm-platforms-and-access-tokens) to learn more. 1. Configure Git credentials for your SCM platform with the org, group, or repository URL that hosts your private dependencies and an access token. ```bash theme={null} git config --global url."https://oauth2:@/".insteadOf "https:///" ``` Replace: * `` with your access token. * `` with your GitHub Enterprise Server hostname. * `` with your GitHub organization or repository path segment. ```bash theme={null} git config --global url."https://oauth2:@/".insteadOf "https:///" ``` Replace: * `` with your personal access token. * `` with `gitlab.com` or your self-managed hostname. * `` with your GitLab group or subgroup path. ```bash theme={null} git config --global url."https://x-token-auth:@/".insteadOf "https:///" ``` Replace: * `` with your Bitbucket access token. * `` with your Bitbucket hostname. * `` with your Bitbucket workspace name. * If your project uses Go, set `GOPRIVATE` to a comma-separated list of private Git host and organization patterns, in the same format as your `git config` URLs. For example, if your GitHub org is `abccorp` and your GitLab group is `widgetco`, set: ```bash theme={null} export GOPRIVATE="github.com/abccorp/*,gitlab.com/widgetco/*" ``` 2. Scan the repository. ```bash theme={null} endorctl scan ``` ### Scan an example repository To scan the example repository `https://github.com/OWASP-Benchmark/BenchmarkJava.git`, follow these steps after you [authenticate to Endor Labs](/setup-deployment/cli#authenticate-to-endor-labs): 1. Clone the repository `https://github.com/OWASP-Benchmark/BenchmarkJava.git` ```bash theme={null} git clone https://github.com/OWASP-Benchmark/BenchmarkJava.git ``` 2. Navigate to the repository on your local system ```bash theme={null} cd BenchmarkJava ``` 3. Build the repository’s package with Maven: ```bash theme={null} mvn clean install ``` 4. Scan the repository ```bash theme={null} endorctl scan ``` ### Scan for SAST To run a SAST scan from the project root to identify potential security weaknesses in your source code, run the following command: ```bash theme={null} endorctl scan --sast ``` To scan a different working directory, set `--path`: ```bash theme={null} endorctl scan --sast --path=/path/to/code ``` To enable AI triage of SAST findings (Code Pro license required), add `--ai-sast-analysis=agent-fallback`. For prerequisites, flags, and AI analysis behavior, see [Run a SAST scan](/scan/sast/run-a-sast-scan). **AI-assisted SAST triage** You can enable AI-assisted triage using `--ai-sast-analysis=agent-fallback`. See [Run a SAST scan](/scan/sast/run-a-sast-scan) for details. ### Scanning for leaked secrets To scan for all potentially leaked secrets in the checked out branch of your repository, run the following command: ```bash theme={null} endorctl scan --secrets ``` Secrets can leak outside the context of your repositories main branch and be present in older branches or those that are under active development. To identify these, Endor Labs inspects the Git logs of the repository. To scan for all potentially leaked secrets in all branches of your repository, run the following command: ```bash theme={null} endorctl scan --secrets --git-logs ``` See [Scan for leaked secrets](/scan/secrets/scan-secrets) for additional configuration options and workflow details. ### Scan for GitHub misconfigurations Endor Labs allows teams to scan their repository for configuration best practices in alignment with organizational policy. #### Prerequisites To scan the GitHub repository, you must have: * The GitHub repository HTTPS clone URL * A personal access token with access administrative access to the repository. For help creating a personal access token see [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). If you are on a self-hosted GitHub Enterprise Server, you should also have: * The GitHub API URL (This is typically the FQDN of the GitHub server) * A local copy of the CA Certificate if the certificate is self-signed or from a private CA #### Run a misconfiguration scan To scan a GitHub repository for misconfigurations: 1. Export your personal access token as an environment variable: ```bash theme={null} export GITHUB_TOKEN= ``` 2. Scan the repository to retrieve configuration information and analyze the configuration against organizational policy or configuration best practices: ```bash theme={null} endorctl scan --repository-http-clone-url=https://github.com//.git --github ``` For source control systems on the GitHub Enterprise Server, you must set the `--github-api-url` flag to your GitHub Enterprise server domain name: ```bash theme={null} endorctl scan --github-api-url=https:// --repository-http-clone-url=https:////.git --github ``` # Setup & Deployment Source: https://docs.endorlabs.com/setup-deployment/index Learn multiple methods to deploy the Endor Labs application across your repositories and pipelines. Endor Labs deployment depends on the scans that you want to do in your environment. This section provides information on how to deploy Endor Labs across your software development lifecycle. ## Choose your deployment method Endor Labs offers multiple deployment options to fit your organization's needs: # Endor Labs MCP server in Google Antigravity Source: https://docs.endorlabs.com/setup-deployment/mcp/antigravity/index Learn how to deploy and run the Endor Labs MCP server in Google Antigravity. Scan dependencies, detect vulnerabilities, find leaked secrets, and review code for security issues directly inside Google Antigravity, powered by your AI agent. You can also connect the [Endor Labs documentation MCP server](/introduction/docs-mcp-server) to get accurate, real-time answers about Endor Labs directly in your AI tools. The Endor Labs MCP server runs locally on your machine as a lightweight process. Your IDE or CLI launches it through `npx` or a system-installed `endorctl` and communicates with it over stdio. When the AI agent needs security context, the server calls the Endor Labs cloud platform and returns the results. The server uses the stdio transport only, so configure it with a `command` and `args` entry rather than an HTTP (`type: http`) URL. ## What you can do With the Endor Labs MCP server, you can: * **Check dependency safety** before adding a new package * **Scan for vulnerabilities and malware** in your open source dependencies * **Find leaked secrets** accidentally committed in your Git history * **Run static analysis (SAST)** on your code with the `scan` tool * **Run AI security reviews** on your code changes (Enterprise Edition) The MCP server returns the full set of findings for the dependency, package, or code you ask about. It does not perform function-level reachability analysis and does not filter findings by an action policy. For reachability and policy-based findings, run a full Endor Labs scan or use the Endor Labs platform. **Node.js: 18 or later required, 24 LTS recommended** The Endor Labs MCP server runs `endorctl` through `npx`, which requires Node.js 18 or later. npm is included with Node.js, so no separate npm installation or version is required. On Node.js versions older than 24, you may see a harmless warning printed before scan output. ```text theme={null} (node:NNNNN) ExperimentalWarning: CommonJS module .../debug/src/node.js is loading ES Module .../supports-color/index.js using require(). ``` This is a Node.js runtime notice, not an error from `endorctl` or the MCP server, and it does not affect scan results. To silence it, upgrade Node.js to 24 LTS or later, then restart your IDE or CLI. Verify with `node --version`. ## Install the MCP server
The Developer Edition is free and uses default security policies from Endor Labs. You do not need an Endor Labs account. When you use the MCP server for the first time, a browser window opens for authentication through GitHub, GitLab, or Google. On the agent panel, click **...**, then select **MCP Servers** > **Manage MCP Servers**. Click **Raw Config** to open the raw configuration editor and add the generated configuration. Have questions? Email us at [community-support@endor.ai](mailto:community-support@endor.ai).
The Enterprise Edition enforces your organization's specific security policies. You need your Endor Labs namespace and an authentication method. Ensure that your developers have Read-Only permissions to Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies) for more details. Generate the Enterprise Edition configuration for your organization. The following parameters are used to configure the MCP server. All parameters are optional. * `ENDOR_MCP_SERVER_AUTH_MODE`: The authentication mode to use for the MCP server. You can use the following authentication modes: `github`, `gitlab`, `google`, `sso`. If you choose `sso`, you must add `ENDOR_MCP_SERVER_AUTH_TENANT` as an additional parameter. If not specified, the MCP server defaults to browser authentication for the Developer Edition. * `ENDOR_NAMESPACE`: The namespace to use for the MCP server. Required for Enterprise Edition to access your organization's specific policies. Not needed for Developer Edition. * `ENDOR_MCP_SERVER_AUTH_TENANT`: The tenant name for SSO authentication. Required when `ENDOR_MCP_SERVER_AUTH_MODE` is set to `sso` for Enterprise Edition access. **Advanced:** You can set scan environment variables in the server's `env` block and the MCP server passes them through to scans. For example, set `SECRETS_RULES_PATH` to point the secret scanner at a custom ruleset. See [Manage secret rules](/scan/secrets/secret-rules/).
## Verify the installation 1. On the agent panel, click **...**, then select **MCP Servers** > **Manage MCP Servers**. 2. Confirm that **endor-cli-tools** appears in the list and is enabled. ### Try a test prompt After installing the MCP server, try the following prompt in your AI chat or CLI to verify that the tools are working. ```text theme={null} Check if the npm package lodash version 4.17.20 has any vulnerabilities ``` The MCP server uses the `check_dependency_for_vulnerabilities` tool to check for known vulnerabilities and return the results. If you see a response with vulnerability details, the MCP server is working correctly. ## Manage MCP servers 1. On the agent panel, click **...**, then select **MCP Servers** > **Manage MCP Servers**. 2. From here, you can view active MCP servers, edit configurations through **Raw Config**, or enable and disable individual servers. ## How to use the Endor Labs MCP server The Endor Labs MCP server provides the following tools: * `check_dependency_for_vulnerabilities`: Check if a dependency in your project is vulnerable. * `check_dependency_for_risks`: Check a dependency for security risks including vulnerabilities and malware. * `get_endor_vulnerability`: Get the details of a specific vulnerability from the Endor Labs vulnerability database. * `get_resource`: Retrieve additional context from commonly used Endor Labs resources about your software, such as findings, vulnerabilities, and projects. * `scan`: Run an Endor Labs security scan to detect risks in your open source dependencies, find common security issues, and spot any credentials accidentally exposed in your Git repository. * `security_review`: Perform security review analysis on code diffs. Analyzes local uncommitted changes (both staged and unstaged) compared to HEAD, or diffs between the main branch and the last commit. The tool sets the [`--diff-scope`](/scan/ai-sast#ai-sast-diff-scans) scan option automatically based on the review type. Requires the Enterprise Edition. You must specify your namespace in the MCP server configuration. You must also enable AI security code review for your namespace in the Endor Labs platform. See [AI security code review](/secure-ai-coding/ai-security-review/) for setup instructions. After you set up the MCP server, you can choose to disable the tools that you do not want to use. ## Configure GEMINI.md Google Antigravity reads `GEMINI.md` files to guide AI development with your project-specific instructions. To enhance the MCP server integration, you can add instructions in `GEMINI.md` at the root of your repository or globally in the `~/.gemini/` directory. 1. Navigate to the root of your repository. 2. Create or edit the `GEMINI.md` file in the root of your repository. For global rules that apply across all projects, create or edit `~/.gemini/GEMINI.md`. 3. Add appropriate rules for your project. For example, you can add a rule to check if the code is free from vulnerabilities. ### Example GEMINI.md instructions You can use the following `GEMINI.md` instructions as a quick start for the Endor Labs MCP server. Modify the instructions to meet your specific organization's needs. For more information, refer to the [Google Antigravity documentation](https://antigravity.google/docs). ```markdown theme={null} # Software Composition Analysis (SCA) Rule (Endor Labs via MCP) This project uses Endor Labs for automated dependency (SCA) scanning, integrated through the MCP server. ## Workflow Every time a manifest or lockfile (package.json, requirements.txt, go.mod, pom.xml, etc.) is created or modified in any way, immediately do the following prior to performing your next task. **Important**: Do not proceed after creating or modifying a manifest file without running this first. - Run `endor-cli-tools` using the `check_dependency_for_vulnerabilities` tool via the MCP server. - Provide the **ecosystem**, **dependency name**, and **version** always when making this tool call. - If a vulnerability or error is identified: - Upgrade to the suggested safe version, or - Replace the dependency with a non-vulnerable alternative. - Re-run the check using `endor-cli-tools` to confirm the issue is resolved. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. ``` ```markdown theme={null} # Leaked Secrets Detection Rule (Endor Labs via MCP) This project uses [Endor Labs](https://docs.endorlabs.com/) for automated security scanning, integrated through the MCP server. ## Workflow Whenever a file is modified in the repository, and before the end of an agent session: - Run `endor-cli-tools` using the `scan` tool via the MCP server to check for leaked secrets. - If any secrets or errors are detected: - Remove the exposed secret or correct the error immediately. - Re-run the scan to verify the secret has been properly removed. - Save scan results and remediation steps in a security log or as comments for audit purposes. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. - This scan must use the path of the directory from which the changed files are in. Use absolute paths. ``` ```markdown theme={null} # Static Application Security Testing (SAST) Rule (Endor Labs via MCP) This project uses [Endor Labs](https://docs.endorlabs.com/) for automated SAST, integrated through the MCP server. ## Workflow Whenever a file is modified in the repository, and before the end of an agent session: - Run `endor-cli-tools` using the `scan` tool via the MCP server to perform SAST scans. - If any vulnerabilities or errors are found: - Present the issues to the user. - Recommend and apply appropriate fixes (e.g., input sanitization, validation, escaping, secure APIs). - Save scan results and remediation steps in a security log or as comments for audit purposes. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. - Do not invoke Opengrep directly. - This scan must use the path of the directory from which the changed files are in. Use absolute paths. ``` ## Keep endorctl up to date The default configuration runs `npx -y endorctl`, which downloads the latest published endorctl into the npx cache (`~/.npm/_npx/`) and reuses it on later runs. If you are not getting the latest version, do one of the following: * Clear the npx cache (`~/.npm/_npx/`), then restart your IDE or CLI so the next run downloads the current endorctl. * Pin a specific version by changing `endorctl` to `endorctl@` in your `args`. * Install endorctl yourself and call it directly, with `command` set to `endorctl` and `args` set to `["ai-tools", "mcp-server"]`. Updates are then managed by your package manager, for example `brew upgrade endorctl`. See [Install endorctl](/setup-deployment/cli/). ## Troubleshooting Use the following troubleshooting steps to resolve common issues with the Endor Labs MCP server. Run `npx --version` in your terminal. If the command fails, install [Node.js](https://nodejs.org/) version 18 or later (Node.js 24 LTS recommended). After installing, restart your IDE or CLI to reload the MCP server configuration. Ensure your IDE or CLI can open a browser. Check firewall or security software that might block browser launch. For Enterprise Edition with SSO, verify that `ENDOR_MCP_SERVER_AUTH_MODE` and `ENDOR_MCP_SERVER_AUTH_TENANT` are set correctly in your MCP configuration. Install endorctl using your preferred method and configure the MCP server to call it directly instead of using npx. In the Enterprise Edition install wizard, select **No** under **Using npx?** to generate the correct configuration. Alternatively, replace the `command` and `args` entries in your MCP configuration manually, using your client's configuration format. ```json JSON theme={null} "command": "endorctl", "args": ["ai-tools", "mcp-server"] ``` ```toml Codex config.toml theme={null} command = "endorctl" args = ["ai-tools", "mcp-server"] ``` For installation options, see [Install endorctl](/setup-deployment/cli/). For more details on how npx and a system-installed endorctl differ, see the FAQ entry below. The default MCP server configuration uses `npx -y endorctl` to run endorctl. This command downloads endorctl from the npm registry into a temporary cache (`~/.npm/_npx/`) and runs it from there. It does **not** install endorctl globally and does **not** interact with any existing endorctl binary on your system. If you have endorctl installed separately (for example, through Homebrew or a direct download), the `npx` command runs its own copy and ignores the system-installed version. These two copies are completely independent. To use your existing endorctl installation instead of npx, select **No** under **Using npx?** in the Enterprise Edition install wizard. This generates a configuration that calls `endorctl` directly, in your client's configuration format. ```json JSON theme={null} "command": "endorctl", "args": ["ai-tools", "mcp-server"] ``` ```toml Codex config.toml theme={null} command = "endorctl" args = ["ai-tools", "mcp-server"] ``` With this approach, updates are managed by your existing package manager (for example, `brew upgrade endorctl`). Verify your namespace is correct and your user has `Read-Only` permissions in Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies/) for details. Also ensure endorctl is on your PATH if you installed it globally instead of using npx. On Windows, ensure the following prerequisites are met: * Node.js is installed * npm global bin directory is in your PATH #### Install Node.js If Node.js is not installed, download and install the **LTS version** from [nodejs.org](https://nodejs.org/). During installation, ensure the option to add Node.js to PATH is selected. #### Configure the PATH environment variable After installing Node.js, verify that the npm global bin directory is in your PATH: 1. Run the following command in the command line. ```powershell theme={null} npm config get prefix ``` This returns the npm global directory path, typically `C:\Users\\AppData\Roaming\npm`. 2. Add the npm global directory path to the **Path** variable under **User variables** in your system's environment variables settings. 3. Restart for the PATH changes to take effect. #### Verify the setup Run the following command in your terminal. ```powershell theme={null} npx --version ``` If this returns a version number, your Windows setup is complete and the MCP server can use `npx` to run endorctl. # Endor Labs MCP server in Augment Code Source: https://docs.endorlabs.com/setup-deployment/mcp/augment-code/index Learn how to deploy and run the Endor Labs MCP server in Augment Code. Scan dependencies, detect vulnerabilities, find leaked secrets, and review code for security issues directly inside Augment Code, powered by your AI agent. You can also connect the [Endor Labs documentation MCP server](/introduction/docs-mcp-server) to get accurate, real-time answers about Endor Labs directly in your AI tools. The Endor Labs MCP server runs locally on your machine as a lightweight process. Your IDE or CLI launches it through `npx` or a system-installed `endorctl` and communicates with it over stdio. When the AI agent needs security context, the server calls the Endor Labs cloud platform and returns the results. The server uses the stdio transport only, so configure it with a `command` and `args` entry rather than an HTTP (`type: http`) URL. ## What you can do With the Endor Labs MCP server, you can: * **Check dependency safety** before adding a new package * **Scan for vulnerabilities and malware** in your open source dependencies * **Find leaked secrets** accidentally committed in your Git history * **Run static analysis (SAST)** on your code with the `scan` tool * **Run AI security reviews** on your code changes (Enterprise Edition) The MCP server returns the full set of findings for the dependency, package, or code you ask about. It does not perform function-level reachability analysis and does not filter findings by an action policy. For reachability and policy-based findings, run a full Endor Labs scan or use the Endor Labs platform. **Node.js: 18 or later required, 24 LTS recommended** The Endor Labs MCP server runs `endorctl` through `npx`, which requires Node.js 18 or later. npm is included with Node.js, so no separate npm installation or version is required. On Node.js versions older than 24, you may see a harmless warning printed before scan output. ```text theme={null} (node:NNNNN) ExperimentalWarning: CommonJS module .../debug/src/node.js is loading ES Module .../supports-color/index.js using require(). ``` This is a Node.js runtime notice, not an error from `endorctl` or the MCP server, and it does not affect scan results. To silence it, upgrade Node.js to 24 LTS or later, then restart your IDE or CLI. Verify with `node --version`. ## Install the MCP server
The Developer Edition is free and uses default security policies from Endor Labs. You do not need an Endor Labs account. When you use the MCP server for the first time, a browser window opens for authentication through GitHub, GitLab, or Google. Open the Augment Code extension in Visual Studio Code, click the **Settings** icon in the upper right of the Augment panel, then in the **MCP** section choose **Import from JSON** or **+** to add a server. Copy and paste the generated configuration. Alternatively, when adding through the settings panel, set **Name** to `endor-cli-tools` and **Command** to `npx -y endorctl ai-tools mcp-server`. Have questions? Email us at [community-support@endor.ai](mailto:community-support@endor.ai).
The Enterprise Edition enforces your organization's specific security policies. You need your Endor Labs namespace and an authentication method. Ensure that your developers have Read-Only permissions to Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies) for more details. Generate the Enterprise Edition configuration for your organization. The following parameters are used to configure the MCP server. All parameters are optional. * `ENDOR_MCP_SERVER_AUTH_MODE`: The authentication mode to use for the MCP server. You can use the following authentication modes: `github`, `gitlab`, `google`, `sso`. If you choose `sso`, you must add `ENDOR_MCP_SERVER_AUTH_TENANT` as an additional parameter. If not specified, the MCP server defaults to browser authentication for the Developer Edition. * `ENDOR_NAMESPACE`: The namespace to use for the MCP server. Required for Enterprise Edition to access your organization's specific policies. Not needed for Developer Edition. * `ENDOR_MCP_SERVER_AUTH_TENANT`: The tenant name for SSO authentication. Required when `ENDOR_MCP_SERVER_AUTH_MODE` is set to `sso` for Enterprise Edition access. **Advanced:** You can set scan environment variables in the server's `env` block and the MCP server passes them through to scans. For example, set `SECRETS_RULES_PATH` to point the secret scanner at a custom ruleset. See [Manage secret rules](/scan/secrets/secret-rules/).
## Verify the installation 1. Open the Augment Code extension in Visual Studio Code. 2. Click the **Settings** icon and confirm that **endor-cli-tools** appears in the **MCP** section. ### Try a test prompt After installing the MCP server, try the following prompt in your AI chat or CLI to verify that the tools are working. ```text theme={null} Check if the npm package lodash version 4.17.20 has any vulnerabilities ``` The MCP server uses the `check_dependency_for_vulnerabilities` tool to check for known vulnerabilities and return the results. If you see a response with vulnerability details, the MCP server is working correctly. ## Manage MCP server tools 1. Open the Augment Code extension in Visual Studio Code. 2. Click the **Settings** icon in the upper right of the Augment panel. 3. In the **MCP** section, click the **...** button next to **endor-cli-tools**. 4. Edit the configuration or remove the server as needed. ## How to use the Endor Labs MCP server The Endor Labs MCP server provides the following tools: * `check_dependency_for_vulnerabilities`: Check if a dependency in your project is vulnerable. * `check_dependency_for_risks`: Check a dependency for security risks including vulnerabilities and malware. * `get_endor_vulnerability`: Get the details of a specific vulnerability from the Endor Labs vulnerability database. * `get_resource`: Retrieve additional context from commonly used Endor Labs resources about your software, such as findings, vulnerabilities, and projects. * `scan`: Run an Endor Labs security scan to detect risks in your open source dependencies, find common security issues, and spot any credentials accidentally exposed in your Git repository. * `security_review`: Perform security review analysis on code diffs. Analyzes local uncommitted changes (both staged and unstaged) compared to HEAD, or diffs between the main branch and the last commit. The tool sets the [`--diff-scope`](/scan/ai-sast#ai-sast-diff-scans) scan option automatically based on the review type. Requires the Enterprise Edition. You must specify your namespace in the MCP server configuration. You must also enable AI security code review for your namespace in the Endor Labs platform. See [AI security code review](/secure-ai-coding/ai-security-review/) for setup instructions. After you set up the MCP server, you can choose to disable the tools that you do not want to use. ## Keep endorctl up to date The default configuration runs `npx -y endorctl`, which downloads the latest published endorctl into the npx cache (`~/.npm/_npx/`) and reuses it on later runs. If you are not getting the latest version, do one of the following: * Clear the npx cache (`~/.npm/_npx/`), then restart your IDE or CLI so the next run downloads the current endorctl. * Pin a specific version by changing `endorctl` to `endorctl@` in your `args`. * Install endorctl yourself and call it directly, with `command` set to `endorctl` and `args` set to `["ai-tools", "mcp-server"]`. Updates are then managed by your package manager, for example `brew upgrade endorctl`. See [Install endorctl](/setup-deployment/cli/). ## Troubleshooting Use the following troubleshooting steps to resolve common issues with the Endor Labs MCP server. Run `npx --version` in your terminal. If the command fails, install [Node.js](https://nodejs.org/) version 18 or later (Node.js 24 LTS recommended). After installing, restart your IDE or CLI to reload the MCP server configuration. Ensure your IDE or CLI can open a browser. Check firewall or security software that might block browser launch. For Enterprise Edition with SSO, verify that `ENDOR_MCP_SERVER_AUTH_MODE` and `ENDOR_MCP_SERVER_AUTH_TENANT` are set correctly in your MCP configuration. Install endorctl using your preferred method and configure the MCP server to call it directly instead of using npx. In the Enterprise Edition install wizard, select **No** under **Using npx?** to generate the correct configuration. Alternatively, replace the `command` and `args` entries in your MCP configuration manually, using your client's configuration format. ```json JSON theme={null} "command": "endorctl", "args": ["ai-tools", "mcp-server"] ``` ```toml Codex config.toml theme={null} command = "endorctl" args = ["ai-tools", "mcp-server"] ``` For installation options, see [Install endorctl](/setup-deployment/cli/). For more details on how npx and a system-installed endorctl differ, see the FAQ entry below. The default MCP server configuration uses `npx -y endorctl` to run endorctl. This command downloads endorctl from the npm registry into a temporary cache (`~/.npm/_npx/`) and runs it from there. It does **not** install endorctl globally and does **not** interact with any existing endorctl binary on your system. If you have endorctl installed separately (for example, through Homebrew or a direct download), the `npx` command runs its own copy and ignores the system-installed version. These two copies are completely independent. To use your existing endorctl installation instead of npx, select **No** under **Using npx?** in the Enterprise Edition install wizard. This generates a configuration that calls `endorctl` directly, in your client's configuration format. ```json JSON theme={null} "command": "endorctl", "args": ["ai-tools", "mcp-server"] ``` ```toml Codex config.toml theme={null} command = "endorctl" args = ["ai-tools", "mcp-server"] ``` With this approach, updates are managed by your existing package manager (for example, `brew upgrade endorctl`). Verify your namespace is correct and your user has `Read-Only` permissions in Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies/) for details. Also ensure endorctl is on your PATH if you installed it globally instead of using npx. On Windows, ensure the following prerequisites are met: * Node.js is installed * npm global bin directory is in your PATH #### Install Node.js If Node.js is not installed, download and install the **LTS version** from [nodejs.org](https://nodejs.org/). During installation, ensure the option to add Node.js to PATH is selected. #### Configure the PATH environment variable After installing Node.js, verify that the npm global bin directory is in your PATH: 1. Run the following command in the command line. ```powershell theme={null} npm config get prefix ``` This returns the npm global directory path, typically `C:\Users\\AppData\Roaming\npm`. 2. Add the npm global directory path to the **Path** variable under **User variables** in your system's environment variables settings. 3. Restart for the PATH changes to take effect. #### Verify the setup Run the following command in your terminal. ```powershell theme={null} npx --version ``` If this returns a version number, your Windows setup is complete and the MCP server can use `npx` to run endorctl. # Endor Labs MCP server in Claude Code Source: https://docs.endorlabs.com/setup-deployment/mcp/claude-code/index Learn how to deploy and run the Endor Labs MCP server in Claude Code. Scan dependencies, detect vulnerabilities, find leaked secrets, and review code for security issues directly inside Claude Code, powered by your AI agent. You can also connect the [Endor Labs documentation MCP server](/introduction/docs-mcp-server) to get accurate, real-time answers about Endor Labs directly in your AI tools. The Endor Labs MCP server runs locally on your machine as a lightweight process. Your IDE or CLI launches it through `npx` or a system-installed `endorctl` and communicates with it over stdio. When the AI agent needs security context, the server calls the Endor Labs cloud platform and returns the results. The server uses the stdio transport only, so configure it with a `command` and `args` entry rather than an HTTP (`type: http`) URL. ## What you can do With the Endor Labs MCP server, you can: * **Check dependency safety** before adding a new package * **Scan for vulnerabilities and malware** in your open source dependencies * **Find leaked secrets** accidentally committed in your Git history * **Run static analysis (SAST)** on your code with the `scan` tool * **Run AI security reviews** on your code changes (Enterprise Edition) The MCP server returns the full set of findings for the dependency, package, or code you ask about. It does not perform function-level reachability analysis and does not filter findings by an action policy. For reachability and policy-based findings, run a full Endor Labs scan or use the Endor Labs platform. **Node.js: 18 or later required, 24 LTS recommended** The Endor Labs MCP server runs `endorctl` through `npx`, which requires Node.js 18 or later. npm is included with Node.js, so no separate npm installation or version is required. On Node.js versions older than 24, you may see a harmless warning printed before scan output. ```text theme={null} (node:NNNNN) ExperimentalWarning: CommonJS module .../debug/src/node.js is loading ES Module .../supports-color/index.js using require(). ``` This is a Node.js runtime notice, not an error from `endorctl` or the MCP server, and it does not affect scan results. To silence it, upgrade Node.js to 24 LTS or later, then restart your IDE or CLI. Verify with `node --version`. ## Install the MCP server
The Developer Edition is free and uses default security policies from Endor Labs. You do not need an Endor Labs account. When you use the MCP server for the first time, a browser window opens for authentication through GitHub, GitLab, or Google.
Run the following command in your terminal to install the MCP server. ```shell theme={null} claude mcp add endor-cli-tools -- npx -y endorctl ai-tools mcp-server ``` For manual configuration, copy and paste the following configuration directly into your MCP configuration file. ```json theme={null} { "mcpServers": { "endor-cli-tools": { "type": "stdio", "command": "npx", "args": [ "-y", "endorctl", "ai-tools", "mcp-server" ] } } } ``` Have questions? Email us at [community-support@endor.ai](mailto:community-support@endor.ai).
The Enterprise Edition enforces your organization's specific security policies. You need your Endor Labs namespace and an authentication method. Ensure that your developers have Read-Only permissions to Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies) for more details. Generate the Enterprise Edition configuration for your organization. The following parameters are used to configure the MCP server. All parameters are optional. * `ENDOR_MCP_SERVER_AUTH_MODE`: The authentication mode to use for the MCP server. You can use the following authentication modes: `github`, `gitlab`, `google`, `sso`. If you choose `sso`, you must add `ENDOR_MCP_SERVER_AUTH_TENANT` as an additional parameter. If not specified, the MCP server defaults to browser authentication for the Developer Edition. * `ENDOR_NAMESPACE`: The namespace to use for the MCP server. Required for Enterprise Edition to access your organization's specific policies. Not needed for Developer Edition. * `ENDOR_MCP_SERVER_AUTH_TENANT`: The tenant name for SSO authentication. Required when `ENDOR_MCP_SERVER_AUTH_MODE` is set to `sso` for Enterprise Edition access. **Advanced:** You can set scan environment variables in the server's `env` block and the MCP server passes them through to scans. For example, set `SECRETS_RULES_PATH` to point the secret scanner at a custom ruleset. See [Manage secret rules](/scan/secrets/secret-rules/).
## Verify the installation ```bash theme={null} claude mcp list ``` Confirm that **endor-cli-tools** appears in the list. You can also use `/mcp` in Claude Code to view active MCP servers. ### Try a test prompt After installing the MCP server, try the following prompt in your AI chat or CLI to verify that the tools are working. ```text theme={null} Check if the npm package lodash version 4.17.20 has any vulnerabilities ``` The MCP server uses the `check_dependency_for_vulnerabilities` tool to check for known vulnerabilities and return the results. If you see a response with vulnerability details, the MCP server is working correctly. ## Scope options Claude Code supports three MCP configuration scopes: * `--scope local`: Available only to you in the current project (default). * `--scope project`: Shared with everyone in the project via `.mcp.json` file. * `--scope user`: Available to you across all projects. ## Manage MCP servers ```bash theme={null} claude mcp list claude mcp get endor-cli-tools claude mcp remove endor-cli-tools ``` In Claude Code, use `/mcp` to view and manage your active MCP servers. ## How to use the Endor Labs MCP server The Endor Labs MCP server provides the following tools: * `check_dependency_for_vulnerabilities`: Check if a dependency in your project is vulnerable. * `check_dependency_for_risks`: Check a dependency for security risks including vulnerabilities and malware. * `get_endor_vulnerability`: Get the details of a specific vulnerability from the Endor Labs vulnerability database. * `get_resource`: Retrieve additional context from commonly used Endor Labs resources about your software, such as findings, vulnerabilities, and projects. * `scan`: Run an Endor Labs security scan to detect risks in your open source dependencies, find common security issues, and spot any credentials accidentally exposed in your Git repository. * `security_review`: Perform security review analysis on code diffs. Analyzes local uncommitted changes (both staged and unstaged) compared to HEAD, or diffs between the main branch and the last commit. The tool sets the [`--diff-scope`](/scan/ai-sast#ai-sast-diff-scans) scan option automatically based on the review type. Requires the Enterprise Edition. You must specify your namespace in the MCP server configuration. You must also enable AI security code review for your namespace in the Endor Labs platform. See [AI security code review](/secure-ai-coding/ai-security-review/) for setup instructions. After you set up the MCP server, you can choose to disable the tools that you do not want to use. ## Configure CLAUDE.md To enhance the MCP server integration, you can add instructions in `CLAUDE.md` at the root of your repository. Claude Code reads `CLAUDE.md` files to guide AI development with your project-specific instructions. 1. Navigate to the root of your repository. 2. Create or edit the `CLAUDE.md` file in the root of your repository. 3. Add appropriate rules for your project. For example, you can add a rule to check if the code is free from vulnerabilities. ### Example CLAUDE.md instructions You can use the following `CLAUDE.md` instructions as a quick start for the Endor Labs MCP server. Modify the instructions to meet your specific organization's needs. For more information, refer to the [Claude Code documentation](https://code.claude.com/docs/en/overview). ```markdown theme={null} # Software Composition Analysis (SCA) Rule (Endor Labs via MCP) This project uses Endor Labs for automated dependency (SCA) scanning, integrated through the MCP server. ## Workflow Every time a manifest or lockfile (package.json, requirements.txt, go.mod, pom.xml, etc.) is created or modified in any way, immediately do the following prior to performing your next task. **Important**: Do not proceed after creating or modifying a manifest file without running this first. - Run `endor-cli-tools` using the `check_dependency_for_vulnerabilities` tool via the MCP server. - Provide the **ecosystem**, **dependency name**, and **version** always when making this tool call. - If a vulnerability or error is identified: - Upgrade to the suggested safe version, or - Replace the dependency with a non-vulnerable alternative. - Re-run the check using `endor-cli-tools` to confirm the issue is resolved. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. ``` ```markdown theme={null} # Leaked Secrets Detection Rule (Endor Labs via MCP) This project uses [Endor Labs](https://docs.endorlabs.com/) for automated security scanning, integrated through the MCP server. ## Workflow Whenever a file is modified in the repository, and before the end of an agent session: - Run `endor-cli-tools` using the `scan` tool via the MCP server to check for leaked secrets. - If any secrets or errors are detected: - Remove the exposed secret or correct the error immediately. - Re-run the scan to verify the secret has been properly removed. - Save scan results and remediation steps in a security log or as comments for audit purposes. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. - This scan must use the path of the directory from which the changed files are in. Use absolute paths. ``` ```markdown theme={null} # Static Application Security Testing (SAST) Rule (Endor Labs via MCP) This project uses [Endor Labs](https://docs.endorlabs.com/) for automated SAST, integrated through the MCP server. ## Workflow Whenever a file is modified in the repository, and before the end of an agent session: - Run `endor-cli-tools` using the `scan` tool via the MCP server to perform SAST scans. - If any vulnerabilities or errors are found: - Present the issues to the user. - Recommend and apply appropriate fixes (e.g., input sanitization, validation, escaping, secure APIs). - Save scan results and remediation steps in a security log or as comments for audit purposes. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. - Do not invoke Opengrep directly. - This scan must use the path of the directory from which the changed files are in. Use absolute paths. ``` ## Keep endorctl up to date The default configuration runs `npx -y endorctl`, which downloads the latest published endorctl into the npx cache (`~/.npm/_npx/`) and reuses it on later runs. If you are not getting the latest version, do one of the following: * Clear the npx cache (`~/.npm/_npx/`), then restart your IDE or CLI so the next run downloads the current endorctl. * Pin a specific version by changing `endorctl` to `endorctl@` in your `args`. * Install endorctl yourself and call it directly, with `command` set to `endorctl` and `args` set to `["ai-tools", "mcp-server"]`. Updates are then managed by your package manager, for example `brew upgrade endorctl`. See [Install endorctl](/setup-deployment/cli/). ## Troubleshooting Use the following troubleshooting steps to resolve common issues with the Endor Labs MCP server. Run `npx --version` in your terminal. If the command fails, install [Node.js](https://nodejs.org/) version 18 or later (Node.js 24 LTS recommended). After installing, restart your IDE or CLI to reload the MCP server configuration. Ensure your IDE or CLI can open a browser. Check firewall or security software that might block browser launch. For Enterprise Edition with SSO, verify that `ENDOR_MCP_SERVER_AUTH_MODE` and `ENDOR_MCP_SERVER_AUTH_TENANT` are set correctly in your MCP configuration. Install endorctl using your preferred method and configure the MCP server to call it directly instead of using npx. In the Enterprise Edition install wizard, select **No** under **Using npx?** to generate the correct configuration. Alternatively, replace the `command` and `args` entries in your MCP configuration manually, using your client's configuration format. ```json JSON theme={null} "command": "endorctl", "args": ["ai-tools", "mcp-server"] ``` ```toml Codex config.toml theme={null} command = "endorctl" args = ["ai-tools", "mcp-server"] ``` For installation options, see [Install endorctl](/setup-deployment/cli/). For more details on how npx and a system-installed endorctl differ, see the FAQ entry below. The default MCP server configuration uses `npx -y endorctl` to run endorctl. This command downloads endorctl from the npm registry into a temporary cache (`~/.npm/_npx/`) and runs it from there. It does **not** install endorctl globally and does **not** interact with any existing endorctl binary on your system. If you have endorctl installed separately (for example, through Homebrew or a direct download), the `npx` command runs its own copy and ignores the system-installed version. These two copies are completely independent. To use your existing endorctl installation instead of npx, select **No** under **Using npx?** in the Enterprise Edition install wizard. This generates a configuration that calls `endorctl` directly, in your client's configuration format. ```json JSON theme={null} "command": "endorctl", "args": ["ai-tools", "mcp-server"] ``` ```toml Codex config.toml theme={null} command = "endorctl" args = ["ai-tools", "mcp-server"] ``` With this approach, updates are managed by your existing package manager (for example, `brew upgrade endorctl`). Verify your namespace is correct and your user has `Read-Only` permissions in Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies/) for details. Also ensure endorctl is on your PATH if you installed it globally instead of using npx. On Windows, ensure the following prerequisites are met: * Node.js is installed * npm global bin directory is in your PATH #### Install Node.js If Node.js is not installed, download and install the **LTS version** from [nodejs.org](https://nodejs.org/). During installation, ensure the option to add Node.js to PATH is selected. #### Configure the PATH environment variable After installing Node.js, verify that the npm global bin directory is in your PATH: 1. Run the following command in the command line. ```powershell theme={null} npm config get prefix ``` This returns the npm global directory path, typically `C:\Users\\AppData\Roaming\npm`. 2. Add the npm global directory path to the **Path** variable under **User variables** in your system's environment variables settings. 3. Restart for the PATH changes to take effect. #### Verify the setup Run the following command in your terminal. ```powershell theme={null} npx --version ``` If this returns a version number, your Windows setup is complete and the MCP server can use `npx` to run endorctl. # Endor Labs MCP server in OpenAI Codex Source: https://docs.endorlabs.com/setup-deployment/mcp/codex/index Learn how to deploy and run the Endor Labs MCP server in OpenAI Codex. Scan dependencies, detect vulnerabilities, find leaked secrets, and review code for security issues directly inside OpenAI Codex, powered by your AI agent. You can also connect the [Endor Labs documentation MCP server](/introduction/docs-mcp-server) to get accurate, real-time answers about Endor Labs directly in your AI tools. The Endor Labs MCP server runs locally on your machine as a lightweight process. Your IDE or CLI launches it through `npx` or a system-installed `endorctl` and communicates with it over stdio. When the AI agent needs security context, the server calls the Endor Labs cloud platform and returns the results. The server uses the stdio transport only, so configure it with a `command` and `args` entry rather than an HTTP (`type: http`) URL. ## What you can do With the Endor Labs MCP server, you can: * **Check dependency safety** before adding a new package * **Scan for vulnerabilities and malware** in your open source dependencies * **Find leaked secrets** accidentally committed in your Git history * **Run static analysis (SAST)** on your code with the `scan` tool * **Run AI security reviews** on your code changes (Enterprise Edition) The MCP server returns the full set of findings for the dependency, package, or code you ask about. It does not perform function-level reachability analysis and does not filter findings by an action policy. For reachability and policy-based findings, run a full Endor Labs scan or use the Endor Labs platform. **Node.js: 18 or later required, 24 LTS recommended** The Endor Labs MCP server runs `endorctl` through `npx`, which requires Node.js 18 or later. npm is included with Node.js, so no separate npm installation or version is required. On Node.js versions older than 24, you may see a harmless warning printed before scan output. ```text theme={null} (node:NNNNN) ExperimentalWarning: CommonJS module .../debug/src/node.js is loading ES Module .../supports-color/index.js using require(). ``` This is a Node.js runtime notice, not an error from `endorctl` or the MCP server, and it does not affect scan results. To silence it, upgrade Node.js to 24 LTS or later, then restart your IDE or CLI. Verify with `node --version`. ## Install the MCP server
The Developer Edition is free and uses default security policies from Endor Labs. You do not need an Endor Labs account. When you use the MCP server for the first time, a browser window opens for authentication through GitHub, GitLab, or Google.
Run the following command in your terminal to install the MCP server. ```shell theme={null} codex mcp add endor-cli-tools -- npx -y endorctl ai-tools mcp-server ``` For manual configuration, copy and paste the following configuration directly into your `config.toml` file. ```toml theme={null} [mcp_servers.endor-cli-tools] command = "npx" args = ["-y", "endorctl", "ai-tools", "mcp-server"] ``` Have questions? Email us at [community-support@endor.ai](mailto:community-support@endor.ai).
The Enterprise Edition enforces your organization's specific security policies. You need your Endor Labs namespace and an authentication method. Ensure that your developers have Read-Only permissions to Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies) for more details. Generate the Enterprise Edition configuration for your organization. The following parameters are used to configure the MCP server. All parameters are optional. * `ENDOR_MCP_SERVER_AUTH_MODE`: The authentication mode to use for the MCP server. You can use the following authentication modes: `github`, `gitlab`, `google`, `sso`. If you choose `sso`, you must add `ENDOR_MCP_SERVER_AUTH_TENANT` as an additional parameter. If not specified, the MCP server defaults to browser authentication for the Developer Edition. * `ENDOR_NAMESPACE`: The namespace to use for the MCP server. Required for Enterprise Edition to access your organization's specific policies. Not needed for Developer Edition. * `ENDOR_MCP_SERVER_AUTH_TENANT`: The tenant name for SSO authentication. Required when `ENDOR_MCP_SERVER_AUTH_MODE` is set to `sso` for Enterprise Edition access. **Advanced:** You can set scan environment variables in the server's `env` block and the MCP server passes them through to scans. For example, set `SECRETS_RULES_PATH` to point the secret scanner at a custom ruleset. See [Manage secret rules](/scan/secrets/secret-rules/).
## Verify the installation ```bash theme={null} codex mcp list ``` Confirm that **endor-cli-tools** appears in the list. You can also use `/mcp` in the Codex TUI to view active MCP servers. ### Try a test prompt After installing the MCP server, try the following prompt in your AI chat or CLI to verify that the tools are working. ```text theme={null} Check if the npm package lodash version 4.17.20 has any vulnerabilities ``` The MCP server uses the `check_dependency_for_vulnerabilities` tool to check for known vulnerabilities and return the results. If you see a response with vulnerability details, the MCP server is working correctly. ## Manage MCP server tools In the Codex TUI, use `/mcp` to see your active MCP servers. You can also disable specific tools in the `config.toml` file: ```toml theme={null} [mcp_servers.endor-cli-tools] command = "npx" args = ["-y", "endorctl", "ai-tools", "mcp-server"] enabled_tools = ["check_dependency_for_vulnerabilities", "scan"] ``` ## How to use the Endor Labs MCP server The Endor Labs MCP server provides the following tools: * `check_dependency_for_vulnerabilities`: Check if a dependency in your project is vulnerable. * `check_dependency_for_risks`: Check a dependency for security risks including vulnerabilities and malware. * `get_endor_vulnerability`: Get the details of a specific vulnerability from the Endor Labs vulnerability database. * `get_resource`: Retrieve additional context from commonly used Endor Labs resources about your software, such as findings, vulnerabilities, and projects. * `scan`: Run an Endor Labs security scan to detect risks in your open source dependencies, find common security issues, and spot any credentials accidentally exposed in your Git repository. * `security_review`: Perform security review analysis on code diffs. Analyzes local uncommitted changes (both staged and unstaged) compared to HEAD, or diffs between the main branch and the last commit. The tool sets the [`--diff-scope`](/scan/ai-sast#ai-sast-diff-scans) scan option automatically based on the review type. Requires the Enterprise Edition. You must specify your namespace in the MCP server configuration. You must also enable AI security code review for your namespace in the Endor Labs platform. See [AI security code review](/secure-ai-coding/ai-security-review/) for setup instructions. After you set up the MCP server, you can choose to disable the tools that you do not want to use. ## Configure AGENTS.md To enhance the MCP server integration, you can add instructions in `AGENTS.md` at the root of your repository. Codex reads `AGENTS.md` files to guide AI development with your project-specific instructions. 1. Navigate to the root of your repository. 2. Create or edit the `AGENTS.md` file in the root of your repository. 3. Add appropriate rules for your project. For example, you can add a rule to check if the code is free from vulnerabilities. ### Example AGENTS.md instructions You can use the following `AGENTS.md` instructions as a quick start for the Endor Labs MCP server. Modify the instructions to meet your specific organization's needs. For more information, refer to the [OpenAI Codex AGENTS.md documentation](https://developers.openai.com/codex/guides/agents-md). ```markdown theme={null} # Software Composition Analysis (SCA) Rule (Endor Labs via MCP) This project uses Endor Labs for automated dependency (SCA) scanning, integrated through the MCP server. ## Workflow Every time a manifest or lockfile (package.json, requirements.txt, go.mod, pom.xml, etc.) is created or modified in any way, immediately do the following prior to performing your next task. **Important**: Do not proceed after creating or modifying a manifest file without running this first. - Run `endor-cli-tools` using the `check_dependency_for_vulnerabilities` tool via the MCP server. - Provide the **ecosystem**, **dependency name**, and **version** always when making this tool call. - If a vulnerability or error is identified: - Upgrade to the suggested safe version, or - Replace the dependency with a non-vulnerable alternative. - Re-run the check using `endor-cli-tools` to confirm the issue is resolved. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. ``` ```markdown theme={null} # Leaked Secrets Detection Rule (Endor Labs via MCP) This project uses [Endor Labs](https://docs.endorlabs.com/) for automated security scanning, integrated through the MCP server. ## Workflow Whenever a file is modified in the repository, and before the end of an agent session: - Run `endor-cli-tools` using the `scan` tool via the MCP server to check for leaked secrets. - If any secrets or errors are detected: - Remove the exposed secret or correct the error immediately. - Re-run the scan to verify the secret has been properly removed. - Save scan results and remediation steps in a security log or as comments for audit purposes. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. - This scan must use the path of the directory from which the changed files are in. Use absolute paths. ``` ```markdown theme={null} # Static Application Security Testing (SAST) Rule (Endor Labs via MCP) This project uses [Endor Labs](https://docs.endorlabs.com/) for automated SAST, integrated through the MCP server. ## Workflow Whenever a file is modified in the repository, and before the end of an agent session: - Run `endor-cli-tools` using the `scan` tool via the MCP server to perform SAST scans. - If any vulnerabilities or errors are found: - Present the issues to the user. - Recommend and apply appropriate fixes (e.g., input sanitization, validation, escaping, secure APIs). - Save scan results and remediation steps in a security log or as comments for audit purposes. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. - Do not invoke Opengrep directly. - This scan must use the path of the directory from which the changed files are in. Use absolute paths. ``` ## Keep endorctl up to date The default configuration runs `npx -y endorctl`, which downloads the latest published endorctl into the npx cache (`~/.npm/_npx/`) and reuses it on later runs. If you are not getting the latest version, do one of the following: * Clear the npx cache (`~/.npm/_npx/`), then restart your IDE or CLI so the next run downloads the current endorctl. * Pin a specific version by changing `endorctl` to `endorctl@` in your `args`. * Install endorctl yourself and call it directly, with `command` set to `endorctl` and `args` set to `["ai-tools", "mcp-server"]`. Updates are then managed by your package manager, for example `brew upgrade endorctl`. See [Install endorctl](/setup-deployment/cli/). ## Troubleshooting Use the following troubleshooting steps to resolve common issues with the Endor Labs MCP server. Run `npx --version` in your terminal. If the command fails, install [Node.js](https://nodejs.org/) version 18 or later (Node.js 24 LTS recommended). After installing, restart your IDE or CLI to reload the MCP server configuration. Ensure your IDE or CLI can open a browser. Check firewall or security software that might block browser launch. For Enterprise Edition with SSO, verify that `ENDOR_MCP_SERVER_AUTH_MODE` and `ENDOR_MCP_SERVER_AUTH_TENANT` are set correctly in your MCP configuration. Install endorctl using your preferred method and configure the MCP server to call it directly instead of using npx. In the Enterprise Edition install wizard, select **No** under **Using npx?** to generate the correct configuration. Alternatively, replace the `command` and `args` entries in your MCP configuration manually, using your client's configuration format. ```json JSON theme={null} "command": "endorctl", "args": ["ai-tools", "mcp-server"] ``` ```toml Codex config.toml theme={null} command = "endorctl" args = ["ai-tools", "mcp-server"] ``` For installation options, see [Install endorctl](/setup-deployment/cli/). For more details on how npx and a system-installed endorctl differ, see the FAQ entry below. The default MCP server configuration uses `npx -y endorctl` to run endorctl. This command downloads endorctl from the npm registry into a temporary cache (`~/.npm/_npx/`) and runs it from there. It does **not** install endorctl globally and does **not** interact with any existing endorctl binary on your system. If you have endorctl installed separately (for example, through Homebrew or a direct download), the `npx` command runs its own copy and ignores the system-installed version. These two copies are completely independent. To use your existing endorctl installation instead of npx, select **No** under **Using npx?** in the Enterprise Edition install wizard. This generates a configuration that calls `endorctl` directly, in your client's configuration format. ```json JSON theme={null} "command": "endorctl", "args": ["ai-tools", "mcp-server"] ``` ```toml Codex config.toml theme={null} command = "endorctl" args = ["ai-tools", "mcp-server"] ``` With this approach, updates are managed by your existing package manager (for example, `brew upgrade endorctl`). Verify your namespace is correct and your user has `Read-Only` permissions in Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies/) for details. Also ensure endorctl is on your PATH if you installed it globally instead of using npx. On Windows, ensure the following prerequisites are met: * Node.js is installed * npm global bin directory is in your PATH #### Install Node.js If Node.js is not installed, download and install the **LTS version** from [nodejs.org](https://nodejs.org/). During installation, ensure the option to add Node.js to PATH is selected. #### Configure the PATH environment variable After installing Node.js, verify that the npm global bin directory is in your PATH: 1. Run the following command in the command line. ```powershell theme={null} npm config get prefix ``` This returns the npm global directory path, typically `C:\Users\\AppData\Roaming\npm`. 2. Add the npm global directory path to the **Path** variable under **User variables** in your system's environment variables settings. 3. Restart for the PATH changes to take effect. #### Verify the setup Run the following command in your terminal. ```powershell theme={null} npx --version ``` If this returns a version number, your Windows setup is complete and the MCP server can use `npx` to run endorctl. # Endor Labs MCP server in Cursor Source: https://docs.endorlabs.com/setup-deployment/mcp/cursor/index Learn how to deploy and run the Endor Labs MCP server in Cursor. Scan dependencies, detect vulnerabilities, find leaked secrets, and review code for security issues directly inside Cursor, powered by your AI agent. You can also connect the [Endor Labs documentation MCP server](/introduction/docs-mcp-server) to get accurate, real-time answers about Endor Labs directly in your AI tools. The Endor Labs MCP server runs locally on your machine as a lightweight process. Your IDE or CLI launches it through `npx` or a system-installed `endorctl` and communicates with it over stdio. When the AI agent needs security context, the server calls the Endor Labs cloud platform and returns the results. The server uses the stdio transport only, so configure it with a `command` and `args` entry rather than an HTTP (`type: http`) URL. ## What you can do With the Endor Labs MCP server, you can: * **Check dependency safety** before adding a new package * **Scan for vulnerabilities and malware** in your open source dependencies * **Find leaked secrets** accidentally committed in your Git history * **Run static analysis (SAST)** on your code with the `scan` tool * **Run AI security reviews** on your code changes (Enterprise Edition) The MCP server returns the full set of findings for the dependency, package, or code you ask about. It does not perform function-level reachability analysis and does not filter findings by an action policy. For reachability and policy-based findings, run a full Endor Labs scan or use the Endor Labs platform. **Node.js: 18 or later required, 24 LTS recommended** The Endor Labs MCP server runs `endorctl` through `npx`, which requires Node.js 18 or later. npm is included with Node.js, so no separate npm installation or version is required. On Node.js versions older than 24, you may see a harmless warning printed before scan output. ```text theme={null} (node:NNNNN) ExperimentalWarning: CommonJS module .../debug/src/node.js is loading ES Module .../supports-color/index.js using require(). ``` This is a Node.js runtime notice, not an error from `endorctl` or the MCP server, and it does not affect scan results. To silence it, upgrade Node.js to 24 LTS or later, then restart your IDE or CLI. Verify with `node --version`. ## Install the MCP server
The Developer Edition is free and uses default security policies from Endor Labs. You do not need an Endor Labs account. When you use the MCP server for the first time, a browser window opens for authentication through GitHub, GitLab, or Google. Have questions? Email us at [community-support@endor.ai](mailto:community-support@endor.ai).
The Enterprise Edition enforces your organization's specific security policies. You need your Endor Labs namespace and an authentication method. Ensure that your developers have Read-Only permissions to Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies) for more details. Generate the Enterprise Edition configuration for your organization. The following parameters are used to configure the MCP server. All parameters are optional. * `ENDOR_MCP_SERVER_AUTH_MODE`: The authentication mode to use for the MCP server. You can use the following authentication modes: `github`, `gitlab`, `google`, `sso`. If you choose `sso`, you must add `ENDOR_MCP_SERVER_AUTH_TENANT` as an additional parameter. If not specified, the MCP server defaults to browser authentication for the Developer Edition. * `ENDOR_NAMESPACE`: The namespace to use for the MCP server. Required for Enterprise Edition to access your organization's specific policies. Not needed for Developer Edition. * `ENDOR_MCP_SERVER_AUTH_TENANT`: The tenant name for SSO authentication. Required when `ENDOR_MCP_SERVER_AUTH_MODE` is set to `sso` for Enterprise Edition access. **Advanced:** You can set scan environment variables in the server's `env` block and the MCP server passes them through to scans. For example, set `SECRETS_RULES_PATH` to point the secret scanner at a custom ruleset. See [Manage secret rules](/scan/secrets/secret-rules/).
## Verify the installation After installing, select **Settings** > **Cursor Settings** > **Tools & MCP** and confirm **endor-cli-tools** appears in the list and is enabled. ### Try a test prompt After installing the MCP server, try the following prompt in your AI chat or CLI to verify that the tools are working. ```text theme={null} Check if the npm package lodash version 4.17.20 has any vulnerabilities ``` The MCP server uses the `check_dependency_for_vulnerabilities` tool to check for known vulnerabilities and return the results. If you see a response with vulnerability details, the MCP server is working correctly. ## How to use the Endor Labs MCP server The Endor Labs MCP server provides the following tools: * `check_dependency_for_vulnerabilities`: Check if a dependency in your project is vulnerable. * `check_dependency_for_risks`: Check a dependency for security risks including vulnerabilities and malware. * `get_endor_vulnerability`: Get the details of a specific vulnerability from the Endor Labs vulnerability database. * `get_resource`: Retrieve additional context from commonly used Endor Labs resources about your software, such as findings, vulnerabilities, and projects. * `scan`: Run an Endor Labs security scan to detect risks in your open source dependencies, find common security issues, and spot any credentials accidentally exposed in your Git repository. * `security_review`: Perform security review analysis on code diffs. Analyzes local uncommitted changes (both staged and unstaged) compared to HEAD, or diffs between the main branch and the last commit. The tool sets the [`--diff-scope`](/scan/ai-sast#ai-sast-diff-scans) scan option automatically based on the review type. Requires the Enterprise Edition. You must specify your namespace in the MCP server configuration. You must also enable AI security code review for your namespace in the Endor Labs platform. See [AI security code review](/secure-ai-coding/ai-security-review/) for setup instructions. After you set up the MCP server, you can choose to disable the tools that you do not want to use. ## Configure Cursor rules To enhance the MCP server integration, you can add custom rules for your project. These rules are custom prompts specific to your project. 1. Navigate to the root of your repository. 2. In the `.cursor/rules` directory, create an `.mdc` file to add specific instructions. 3. Add appropriate rules for your project in the `.cursor/rules/endorlabs.mdc` file. For example, you can add a rule to check if the code is free from vulnerabilities. ### Example Cursor rules You can use the following Cursor rules as a quick start for the Endor Labs MCP server. Modify the rules to meet your specific organization's needs. We recommend that you store each cursor rule in a separate file. For more information, refer to the [Cursor documentation](https://docs.cursor.com/context/rules). ```yaml theme={null} --- description: "Ensure newly added dependencies are checked for vulnerabilities and project stays clean" globs: '**/package.json, **/package-lock.json, **/yarn.lock, **/pnpm-lock.yaml, **/requirements.txt, **/Pipfile, **/Pipfile.lock, **/pyproject.toml, **/poetry.lock, **/go.mod, **/go.sum, **/Cargo.toml, **/Cargo.lock, **/pom.xml, **/build.gradle, **/build.gradle.kts, **/gradle.lockfile, **/composer.json, **/composer.lock' alwaysApply: true --- # Software Composition Analysis (SCA) Rule (Endor Labs via MCP) This project uses Endor Labs for automated dependency (SCA) scanning, integrated through the MCP server as configured in `.cursor/mcp.json`. ## Workflow Every time a manifest or lockfile listed above is created or modified in any way immediately do the following prior to performing your next task. **Important**: Do not proceed after creating or modifying a manifest file without running this first. Do not write any other code or continue with your existing prompt. This is top priority whenever a manifest file is created or updated. - Run `endor-cli-tools` using the `check_dependency_for_vulnerabilities` tool via the MCP server. - Provide the **ecosystem**, **dependency name**, and **version** always when making this tool call. Do not forget to provide a version. - If a vulnerability or error is identified: - Upgrade to the suggested safe version, or - Replace the dependency with a non-vulnerable alternative. - The AI agent must attempt to automatically correct all detected errors and vulnerabilities before session completion. - Re-run the check using `endor-cli-tools` to confirm the issue is resolved. - If an error occurs in any MCP server tool call (such as missing required parameters like version, invalid arguments, or tool invocation failures): - The AI agent must review the error, determine the cause, and automatically correct the tool call or input parameters. - Re-attempt the tool call with the corrected parameters. - Continue this process until the tool call succeeds or it is determined that remediation is not possible, in which case the issue and reason must be reported. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`) as configured in `.cursor/mcp.json`. Do not invoke `endorctl` directly. - For troubleshooting, ensure the MCP server is running and `endorctl` is installed and accessible in your environment. This rule ensures that all dependency changes are evaluated for risk at the time of introduction, and that the project remains clean and secure after each coding session. The scan may be performed at the end of an agent session, provided all modifications are checked and remediated before session completion. ``` ```yaml theme={null} --- description: "Scan for leaked secrets on file modification" globs: '**/*' alwaysApply: true --- # Leaked Secrets Detection Rule (Endor Labs via MCP) This project uses @Endor Labs for automated security scanning, integrated through the MCP server as configured in `.cursor/mcp.json`. ## Workflow Whenever a file is modified in the repository, and before the end of an agent session: - Run `endor-cli-tools` using the `scan` tool via the MCP server to check for leaked secrets. - Ensure the scan includes all file types and respects `.gitignore` unless otherwise configured. - If any secrets or errors are detected: - Remove the exposed secret or correct the error immediately. - The AI agent must attempt to automatically correct all detected secrets and errors before session completion. - Re-run the scan to verify the secret or error has been properly removed or resolved. - If an error occurs in any MCP server tool call (such as missing required parameters like version, invalid arguments, or tool invocation failures): - The AI agent must review the error, determine the cause, and automatically correct the tool call or input parameters. - Re-attempt the tool call with the corrected parameters. - Continue this process until the tool call succeeds or it is determined that remediation is not possible, in which case the issue and reason must be reported. - Save scan results and remediation steps in a security log or as comments for audit purposes. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`) as configured in `.cursor/mcp.json`. Do not invoke `endorctl` directly. - For troubleshooting, ensure the MCP server is running and `endorctl` is installed and accessible in your environment. - **Important**: This scan must use the path of the directory from which the changed files are in. Do not attempt to set the path directly to a file as it must be a directory. Use absolute paths like /Users/username/mcp-server-demo/backend rather than relative paths like 'backend' This rule ensures no accidental credentials, tokens, API keys, or secrets are committed or remain in the project history. The scan may be performed at the end of an agent session, provided all modifications are checked and remediated before session completion. ``` ```yaml theme={null} --- description: "Run SAST scan using endor-cli-tools on source code changes" globs: '**/*.c, **/*.cpp, **/*.cc, **/*.cs, **/*.go, **/*.java, **/*.js, **/*.jsx, **/*.ts, **/*.tsx, **/*.py, **/*.php, **/*.rb, **/*.rs, **/*.kt, **/*.kts, **/*.scala, **/*.swift, **/*.dart, **/*.html, **/*.yaml, **/*.yml, **/*.json, **/*.xml, **/*.sh, **/*.bash, **/*.clj, **/*.cljs, **/*.ex, **/*.exs, **/*.lua' alwaysApply: true --- # Static Application Security Testing (SAST) Rule (Endor Labs via MCP) This project uses @Endor Labs for automated SAST, integrated through the MCP server as configured in `.cursor/mcp.json`. ## Workflow Whenever a file is modified in the repository, and before the end of an agent session perform the following workflow: - Run `endor-cli-tools` using the `scan` tool via the MCP server to perform SAST scans as described above. - If any vulnerabilities or errors are found: - Present the issues to the user. - The AI agent must attempt to automatically correct all errors and vulnerabilities, including code errors, security issues, and best practice violations, before session completion. - Recommend and apply appropriate fixes (e.g., input sanitization, validation, escaping, secure APIs). - Continue scanning and correcting until all critical issues have been resolved or no further automated remediation is possible. - If an error occurs in any MCP server tool call (such as missing required parameters like version, invalid arguments, or tool invocation failures): - The AI agent must review the error, determine the cause, and automatically correct the tool call or input parameters. - Re-attempt the tool call with the corrected parameters. - Continue this process until the tool call succeeds or it is determined that remediation is not possible, in which case the issue and reason must be reported. - Save scan results and remediation steps in a security log or as comments for audit purposes. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`) as configured in `.cursor/mcp.json`. Do not invoke `endorctl` directly. - For troubleshooting, ensure the MCP server is running and `endorctl` is installed and accessible in your environment. - Do not invoke Opengrep directly. - **Important**: This scan must use the path of the directory from which the changed files are in. Do not attempt to set the path directly to a file as it must be a directory. Use absolute paths like /Users/username/mcp-server-demo/backend rather than relative paths like 'backend' This rule ensures all code changes are automatically reviewed and remediated for common security vulnerabilities and errors using `endor-cli-tools` and the MCP server, with Opengrep as the underlying engine. ``` ## Keep endorctl up to date The default configuration runs `npx -y endorctl`, which downloads the latest published endorctl into the npx cache (`~/.npm/_npx/`) and reuses it on later runs. If you are not getting the latest version, do one of the following: * Clear the npx cache (`~/.npm/_npx/`), then restart your IDE or CLI so the next run downloads the current endorctl. * Pin a specific version by changing `endorctl` to `endorctl@` in your `args`. * Install endorctl yourself and call it directly, with `command` set to `endorctl` and `args` set to `["ai-tools", "mcp-server"]`. Updates are then managed by your package manager, for example `brew upgrade endorctl`. See [Install endorctl](/setup-deployment/cli/). ## Troubleshooting Use the following troubleshooting steps to resolve common issues with the Endor Labs MCP server. Run `npx --version` in your terminal. If the command fails, install [Node.js](https://nodejs.org/) version 18 or later (Node.js 24 LTS recommended). After installing, restart your IDE or CLI to reload the MCP server configuration. Ensure your IDE or CLI can open a browser. Check firewall or security software that might block browser launch. For Enterprise Edition with SSO, verify that `ENDOR_MCP_SERVER_AUTH_MODE` and `ENDOR_MCP_SERVER_AUTH_TENANT` are set correctly in your MCP configuration. Install endorctl using your preferred method and configure the MCP server to call it directly instead of using npx. In the Enterprise Edition install wizard, select **No** under **Using npx?** to generate the correct configuration. Alternatively, replace the `command` and `args` entries in your MCP configuration manually, using your client's configuration format. ```json JSON theme={null} "command": "endorctl", "args": ["ai-tools", "mcp-server"] ``` ```toml Codex config.toml theme={null} command = "endorctl" args = ["ai-tools", "mcp-server"] ``` For installation options, see [Install endorctl](/setup-deployment/cli/). For more details on how npx and a system-installed endorctl differ, see the FAQ entry below. The default MCP server configuration uses `npx -y endorctl` to run endorctl. This command downloads endorctl from the npm registry into a temporary cache (`~/.npm/_npx/`) and runs it from there. It does **not** install endorctl globally and does **not** interact with any existing endorctl binary on your system. If you have endorctl installed separately (for example, through Homebrew or a direct download), the `npx` command runs its own copy and ignores the system-installed version. These two copies are completely independent. To use your existing endorctl installation instead of npx, select **No** under **Using npx?** in the Enterprise Edition install wizard. This generates a configuration that calls `endorctl` directly, in your client's configuration format. ```json JSON theme={null} "command": "endorctl", "args": ["ai-tools", "mcp-server"] ``` ```toml Codex config.toml theme={null} command = "endorctl" args = ["ai-tools", "mcp-server"] ``` With this approach, updates are managed by your existing package manager (for example, `brew upgrade endorctl`). Verify your namespace is correct and your user has `Read-Only` permissions in Endor Labs. See [Authorization policies](/platform-administration/rbac/authorization-policies/) for details. Also ensure endorctl is on your PATH if you installed it globally instead of using npx. On Windows, ensure the following prerequisites are met: * Node.js is installed * npm global bin directory is in your PATH #### Install Node.js If Node.js is not installed, download and install the **LTS version** from [nodejs.org](https://nodejs.org/). During installation, ensure the option to add Node.js to PATH is selected. #### Configure the PATH environment variable After installing Node.js, verify that the npm global bin directory is in your PATH: 1. Run the following command in the command line. ```powershell theme={null} npm config get prefix ``` This returns the npm global directory path, typically `C:\Users\\AppData\Roaming\npm`. 2. Add the npm global directory path to the **Path** variable under **User variables** in your system's environment variables settings. 3. Restart for the PATH changes to take effect. #### Verify the setup Run the following command in your terminal. ```powershell theme={null} npx --version ``` If this returns a version number, your Windows setup is complete and the MCP server can use `npx` to run endorctl. # Endor Labs MCP server in Devin Source: https://docs.endorlabs.com/setup-deployment/mcp/devin/index Learn how to deploy and run the Endor Labs MCP server in Devin. Scan dependencies, detect vulnerabilities, find leaked secrets, and review code for security issues directly inside Devin, powered by your AI agent. You can also connect the [Endor Labs documentation MCP server](/introduction/docs-mcp-server) to get accurate, real-time answers about Endor Labs directly in your AI tools. The Endor Labs MCP server runs locally on your machine as a lightweight process. Your IDE or CLI launches it through `npx` or a system-installed `endorctl` and communicates with it over stdio. When the AI agent needs security context, the server calls the Endor Labs cloud platform and returns the results. The server uses the stdio transport only, so configure it with a `command` and `args` entry rather than an HTTP (`type: http`) URL. **Developer Edition not supported** The Endor Labs MCP server Developer Edition is currently not supported with Devin AI. ## Prerequisites for Endor Labs MCP server Ensure that the following prerequisites are met: * A [Devin](https://devin.ai/) account with access to the MCP Marketplace * Your organization's Endor Labs namespace * Endor Labs API key and secret. See [Endor Labs' API keys](/platform-administration/api-keys/) for more information ## Tools in the Endor Labs MCP server The Endor Labs MCP server provides the following tools: * `check_dependency_for_vulnerabilities`: Check if a dependency in your project is vulnerable. * `check_dependency_for_risks`: Check a dependency for security risks including vulnerabilities and malware. * `get_endor_vulnerability`: Get the details of a specific vulnerability from the Endor Labs vulnerability database. * `get_resource`: Retrieve additional context from commonly used Endor Labs resources about your software, such as findings, vulnerabilities, and projects. * `scan`: Run an Endor Labs security scan to detect risks in your open source dependencies, find common security issues, and spot any credentials accidentally exposed in your Git repository. * `security_review`: Perform security review analysis on code diffs. Analyzes local uncommitted changes (both staged and unstaged) compared to HEAD, or diffs between the main branch and the last commit. The tool sets the [`--diff-scope`](/scan/ai-sast#ai-sast-diff-scans) scan option automatically based on the review type. Requires the Enterprise Edition. You must specify your namespace in the MCP server configuration. You must also enable AI security code review for your namespace in the Endor Labs platform. See [AI security code review](/secure-ai-coding/ai-security-review/) for setup instructions. After you set up the MCP server, you can choose to disable the tools that you do not want to use. **Node.js: 18 or later required, 24 LTS recommended** The Endor Labs MCP server runs `endorctl` through `npx`, which requires Node.js 18 or later. npm is included with Node.js, so no separate npm installation or version is required. On Node.js versions older than 24, you may see a harmless warning printed before scan output. ```text theme={null} (node:NNNNN) ExperimentalWarning: CommonJS module .../debug/src/node.js is loading ES Module .../supports-color/index.js using require(). ``` This is a Node.js runtime notice, not an error from `endorctl` or the MCP server, and it does not affect scan results. To silence it, upgrade Node.js to 24 LTS or later, then restart your IDE or CLI. Verify with `node --version`. ## Add Endor Labs MCP server through the MCP Marketplace 1. Navigate to [Settings > MCP Marketplace](https://app.devin.ai/settings/mcp-marketplace) in Devin. 2. Click **Add Your Own** to add a custom MCP server. 3. Add the following secrets with the corresponding values: * `ENDOR_API_CREDENTIALS_KEY`: Your Endor Labs API key * `ENDOR_API_CREDENTIALS_SECRET`: Your Endor Labs API secret * `ENDOR_NAMESPACE`: Your Endor Labs namespace 4. Add the following configuration under STDIO Configuration: * **Command**: `npx` * **Arguments**: `-y endorctl ai-tools mcp-server -n $ENDOR_NAMESPACE --api-key $ENDOR_API_CREDENTIALS_KEY --api-secret $ENDOR_API_CREDENTIALS_SECRET` 5. Click **Save Changes** to save the MCP server configuration. ### Configuration parameters The following parameters are used to configure the MCP server in Devin: * `ENDOR_API_CREDENTIALS_KEY`: (Required) Your Endor Labs API key. See [API keys](/platform-administration/api-keys) for more information. * `ENDOR_API_CREDENTIALS_SECRET`: (Required) Your Endor Labs API secret. * `ENDOR_NAMESPACE`: (Required) Your Endor Labs namespace to access your organization's policies. ## Manage MCP server tools 1. Navigate to [Settings > MCP Marketplace](https://app.devin.ai/settings/mcp-marketplace) in Devin. 2. Locate the **endor-cli-tools** server in the list. 3. Click the server to view its details and manage its tools. ## Configure Devin Knowledge To enhance the MCP server integration, you can add instructions through Devin Knowledge. Knowledge entries guide Devin's AI development with your project-specific instructions. 1. Navigate to [Settings > Knowledge](https://app.devin.ai/settings/knowledge) in Devin. 2. Create a new Knowledge entry for Endor Labs security scanning. 3. Add appropriate instructions for your project. For example, you can add a rule to check if the code is free from vulnerabilities. You can also create a [Playbook](https://docs.devin.ai/product-guides/creating-playbooks) to automate security scanning workflows with the Endor Labs MCP server. ### Example Knowledge instructions You can use the following Knowledge instructions as a quick start for the Endor Labs MCP server. Modify the instructions to meet your specific organization's needs. For more information, refer to the [Devin Knowledge documentation](https://docs.devin.ai/product-guides/knowledge). ```markdown theme={null} # Software Composition Analysis (SCA) Rule (Endor Labs MCP server) This project uses Endor Labs for automated dependency (SCA) scanning, integrated through the MCP server. ## Workflow Every time a manifest or lockfile (`package.json`, `requirements.txt`, `go.mod`, `pom.xml`, etc.) is created or modified in any way, immediately do the following prior to performing your next task. **Important**: Do not proceed after creating or modifying a manifest file without running this first. - Run `endor-cli-tools` using the `check_dependency_for_vulnerabilities` tool via the MCP server. - Provide the **ecosystem**, **dependency name**, and **version** always when making this tool call. - If a vulnerability or error is identified: - Upgrade to the suggested safe version, or - Replace the dependency with a non-vulnerable alternative. - Re-run the check using `endor-cli-tools` to confirm the issue is resolved. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. ``` ```markdown theme={null} # Leaked Secrets Detection Rule (Endor Labs MCP server) This project uses Endor Labs for automated security scanning, integrated through the MCP server. ## Workflow Whenever a file is modified in the repository, and before the end of a session: - Run `endor-cli-tools` using the `scan` tool via the MCP server to check for leaked secrets. - If any secrets or errors are detected: - Remove the exposed secret or correct the error immediately. - Re-run the scan to verify the secret has been properly removed. - Save scan results and remediation steps in a security log or as comments for audit purposes. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. - This scan must use the path of the directory from which the changed files are in. Use absolute paths. ``` ```markdown theme={null} # Static Application Security Testing (SAST) Rule (Endor Labs MCP server) This project uses Endor Labs for automated SAST, integrated through the MCP server. ## Workflow Whenever a file is modified in the repository, and before the end of a session: - Run `endor-cli-tools` using the `scan` tool via the MCP server to perform SAST scans. - If any vulnerabilities or errors are found: - Present the issues to the user. - Recommend and apply appropriate fixes (e.g., input sanitization, validation, escaping, secure APIs). - Save scan results and remediation steps in a security log or as comments for audit purposes. ## Notes - All scans must be performed using the MCP server integration (`endor-cli-tools`). Do not invoke `endorctl` directly. - Do not invoke Opengrep directly. - This scan must use the path of the directory from which the changed files are in. Use absolute paths. ``` ## Watch how to use Endor Labs with Devin