---
name: Endorlabs
description: Use when scanning repositories for security vulnerabilities, managing findings and policies, configuring CI/CD integrations, or automating security workflows. Reach for this skill when working with SCA (Software Composition Analysis), SAST (Static Application Security Testing), secrets detection, container scanning, or when setting up security policies and remediation workflows.
metadata:
    mintlify-proj: endorlabs
    version: "1.0"
---

# Endor Labs Skill

## Product Summary

Endor Labs is a unified application security platform that scans codebases for vulnerabilities, secrets, license risks, malware, and AI model usage. Agents use it to identify security issues across the software supply chain, triage findings with reachability analysis, and automate remediation. The primary entry points are the **endorctl CLI** (`endorctl scan`), the **REST API** (authenticated with `ENDOR_TOKEN`), and **SCM integrations** (GitHub App, GitLab, Azure DevOps, Bitbucket). Key configuration files include `.endorctl/config.yaml` (CLI auth), `scanprofile.yaml` (scan settings), and policy definitions in YAML or Rego. Documentation: https://docs.endorlabs.com

## When to Use

- **Scanning repositories**: Run `endorctl scan` to detect OSS vulnerabilities, SAST issues, secrets, and misconfigurations in a codebase.
- **Managing findings**: Query, filter, dismiss, or export findings via the UI or REST API. Apply exception policies to exclude findings.
- **Setting up policies**: Create finding, action, exception, or remediation policies to automate triage and enforce security guardrails.
- **CI/CD integration**: Integrate Endor Labs into GitHub Actions, GitLab CI, Azure DevOps, Jenkins, or other CI systems for automated scanning.
- **Configuring scan profiles**: Define which build tools, languages, and scan types (SCA, SAST, secrets) apply to a project.
- **Remediating vulnerabilities**: Use upgrade impact analysis, Endor Patches, or automated pull requests to fix issues.
- **Querying the API**: Use the REST API to retrieve projects, findings, scan results, or manage resources programmatically.

## Quick Reference

### Essential Commands

| Command | Purpose |
|---------|---------|
| `endorctl scan` | Full SCA scan with reachability analysis |
| `endorctl scan --sast` | SAST scan for code vulnerabilities |
| `endorctl scan --secrets` | Scan for leaked secrets in current branch |
| `endorctl scan --secrets --git-logs` | Scan all branches for secrets |
| `endorctl scan --pr` | PR scan (point-in-time, no monitoring) |
| `endorctl scan --dry-run` | Local scan without storing results |
| `endorctl init` | Authenticate and create config file |
| `endorctl auth --print-access-token` | Export current access token |
| `endorctl api list -r Finding` | Query findings via REST API |

### Authentication

| Method | Setup |
|--------|-------|
| **API Key** | Generate in UI (Settings > API Keys), export as `ENDOR_API_CREDENTIALS_KEY` and `ENDOR_API_CREDENTIALS_SECRET` |
| **Token** | Run `endorctl init` to create `~/.endorctl/config.yaml`, or export `ENDOR_TOKEN` |
| **Keyless (CI)** | Use GitHub OIDC, AWS IAM, Azure Managed Identity, or GCP Service Account in CI environments |

### Key File Paths

| File | Purpose |
|------|---------|
| `~/.endorctl/config.yaml` | CLI auth config (API key, tenant, namespace) |
| `scanprofile.yaml` | Scan profile definition (build tools, languages, features) |
| `.endor/ignore.yaml` | Ignore file to exclude findings from scan results |
| `.github/workflows/*.yml` | GitHub Actions workflow for CI integration |

### Scan Types

| Type | Command | Use Case |
|------|---------|----------|
| **SCA** | `endorctl scan` | Detect OSS vulnerabilities with reachability |
| **SAST** | `endorctl scan --sast` | Find code weaknesses (rule-based or AI) |
| **Secrets** | `endorctl scan --secrets` | Detect leaked credentials and API keys |
| **Containers** | `endorctl scan container` | Scan container images for vulnerabilities |
| **GitHub Actions** | `endorctl scan --ghactions` | Scan workflow dependencies |
| **AI Models** | `endorctl scan --ai-models` | Discover LLM/AI model usage |

### Policy Types

| Type | Purpose |
|------|---------|
| **Finding** | Enable/disable scan features or create custom findings |
| **Exception** | Exclude findings from action policies (false positives, accepted risk) |
| **Action** | Trigger workflows (Jira, Slack, PR comments) when findings match criteria |
| **Remediation** | Auto-remediate when upgrades are available |

## Decision Guidance

### When to Use X vs Y

| Scenario | Use | Why |
|----------|-----|-----|
| **Local dev scan vs CI scan** | `--dry-run` for local, normal scan for CI | Dry-run doesn't store results; CI scans enable monitoring |
| **Full scan vs PR scan** | Full for baseline, `--pr` for PRs | PR scans are point-in-time; full scans track trends |
| **Incremental vs full secrets scan** | Incremental by default, `--force-rescan` for full | Incremental is faster; full rescan if rules changed |
| **Exception vs ignore file** | Exception policy for org-wide, ignore file for repo-specific | Policies are centralized; ignore files are per-repo |
| **Action policy vs manual triage** | Action policy for automation, manual for one-offs | Policies scale; manual for exceptions |
| **Scan profile vs auto-detect** | Profile for consistency, auto-detect for simplicity | Profiles ensure reproducibility; auto-detect is quick |

## Workflow

1. **Authenticate**
   - Run `endorctl init` to create `~/.endorctl/config.yaml` with API key and tenant.
   - Or export `ENDOR_TOKEN=$(endorctl auth --print-access-token)` for token-based auth.

2. **Configure scan scope**
   - Define a scan profile (build tools, languages, features) via UI or `scanprofile.yaml`.
   - Or use auto-detection: `endorctl scan --languages=java,python`.

3. **Run scan**
   - Navigate to repository root: `cd /path/to/repo`.
   - Execute scan: `endorctl scan` (SCA), `endorctl scan --sast` (SAST), `endorctl scan --secrets` (secrets).
   - For PR scans: `endorctl scan --pr --scm-pr-id=123 --enable-pr-comments`.

4. **Review findings**
   - View in UI: Findings > filter by severity, category, project.
   - Or query API: `endorctl api list -r Finding --filter='spec.severity=="CRITICAL"'`.

5. **Triage findings**
   - Apply exception policy to dismiss false positives or accepted risks.
   - Or use ignore file (`.endor/ignore.yaml`) for repo-specific exclusions.

6. **Set up policies**
   - Create action policy to trigger Jira, Slack, or PR comments on new findings.
   - Create remediation policy to auto-upgrade when low-risk patches available.

7. **Integrate into CI/CD**
   - Add GitHub Action, GitLab CI, or Jenkins step to run `endorctl scan`.
   - Use keyless auth (OIDC) to avoid storing credentials.
   - Set `--exit-on-policy-warning` to fail build on policy violations.

8. **Monitor and iterate**
   - Review dashboards (OSS Overview, First-Party Code, AI Security Review).
   - Adjust policies based on findings and organizational risk tolerance.

## Common Gotchas

- **Authentication precedence**: Command-line args > `~/.endorctl/config.yaml` > `ENDOR_TOKEN`. If multiple are set, the first takes priority.
- **Namespace mismatch**: Scans default to root namespace. If your token only has access to a child namespace, specify `--namespace=<name>` or set `ENDOR_NAMESPACE`.
- **Baseline not found (exit code 43)**: PR scans with `--pr-baseline=main` fail if `main` hasn't been scanned yet. Run a baseline scan first.
- **Policy violations (exit code 128)**: Blocking action policies cause scan to fail. Set `fail_on_policy: false` in CI config to treat as warning.
- **Secrets scan incremental behavior**: First run is full scan; subsequent runs are incremental. Use `--force-rescan` to re-validate all secrets.
- **Dry-run limitations**: `--dry-run` works only with SCA, SAST, secrets, or AI SAST. Not supported for container scanning.
- **Missing build tools**: Scan fails if build tools (Maven, npm, etc.) aren't installed. Use `endorctl host-check` to verify prerequisites.
- **Git operations fail (exit code 12)**: Ensure repository is properly initialized and HEAD is valid. Check `git status` and `git log`.
- **Transitive vs direct dependencies**: Reachability analysis only flags reachable vulnerabilities. Unreachable transitive deps are low priority.
- **SAST rule changes**: Changing SAST rules triggers full rescan of secrets. Plan rule updates during low-activity periods.

## Verification Checklist

Before submitting work:

- [ ] Authentication works: `endorctl auth --print-access-token` returns a token.
- [ ] Namespace is correct: `endorctl api list -r Project` returns expected projects.
- [ ] Scan completes without errors: `endorctl scan` exits with code 0 (or expected code for policy violations).
- [ ] Findings are visible: Check UI or `endorctl api list -r Finding` returns results.
- [ ] Policies are applied: Verify action policies trigger (Jira, Slack, PR comments).
- [ ] Baseline is set: For PR scans, confirm baseline branch has been scanned.
- [ ] Exit codes are handled: CI/CD pipeline correctly interprets exit codes (0 = success, 128 = policy violation, etc.).
- [ ] Credentials are secure: API keys stored in secrets manager, not in code or logs.
- [ ] Scan profile is consistent: Same profile used across local and CI scans.

## Resources

- **Comprehensive navigation**: https://docs.endorlabs.com/llms.txt
- **Getting started**: https://docs.endorlabs.com/introduction/getting-started
- **endorctl CLI reference**: https://docs.endorlabs.com/developers-api/cli
- **REST API documentation**: https://docs.endorlabs.com/developers-api/rest-api
- **Policies guide**: https://docs.endorlabs.com/platform-administration/policies

---

> For additional documentation and navigation, see: https://docs.endorlabs.com/llms.txt