\n\n## Arnica Dependency Scan – GitHub Action\n\nThe same scanner is available as a **GitHub Action** (composite) and as an **npm CLI** for Azure DevOps, Bitbucket Pipelines, and GitLab CI (`npx @arnica-io/dependency-scan`).\n\nExtend Arnica’s security scanning into complex build environments that pull dependencies from multiple sources or compile packages from source.\nWhen real-time checks aren’t enough, post-build scanning validates SBOMs directly from your CI/CD pipelines via API, returning pass/fail results to enforce security gates before merges or deployments. Ensure consistent policy enforcement and centralized visibility in Arnica’s dashboard, even for environments with intricate dependency resolution.\n\n### Pipeline Examples\n\nReference pipeline files with comments and secret/path notes:\n\n- GitHub Action: `examples/github-action.yml`\n- Azure DevOps: `examples/azure-devops.yml`\n- Bitbucket Pipelines: `examples/bitbucket-pipelines.yml`\n- GitLab CI: `examples/gitlab-ci.yml`\n\n### Quickstart\n\nAdd a workflow that runs on PR events and merges to SLA branches for complete security coverage.\n\n```yaml\nname: Arnica Dependency Security Scan\non:\n pull_request:\n types: [opened, synchronize]\n push:\n branches: [main, develop, staging, production] # Add your SLA branches\n workflow_dispatch:\n\njobs:\n security-scan:\n runs-on: ubuntu-latest\n permissions:\n contents: read\n steps:\n - name: Checkout repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #v6.0.2\n with:\n persist-credentials: false\n\n - name: Dependency Security Scan with Arnica\n id: arnica\n uses: arnica-io/dependency-scan@ab5da123065b211ff1d3b941748edb819153ea08 # v1.0.33\n env:\n ARNICA_API_TOKEN: ${{ secrets.ARNICA_API_TOKEN }}\n with:\n repository-url: ${{ github.server_url }}/${{ github.repository }}\n branch: ${{ github.head_ref || github.ref_name }} # Uses the PR source branch for pull requests, or the current branch for pushes\n scan-path: .\n\n - name: Print scan results\n run: |\n echo \"Scan ID: ${{ steps.arnica.outputs['scan-id'] }}\"\n echo \"Status: ${{ steps.arnica.outputs.status }}\"\n```\n\n### Pinning to a Commit SHA\n\nWhile Arnica's action tags are immutable, as a general best practice we recommend pinning all GitHub Actions to a full commit SHA rather than a tag. SHA pinning ensures your workflows are deterministic and aligned with [GitHub's security hardening guidelines](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-third-party-actions).\n\n```yaml\n# Best practice – pinned to commit SHA\nuses: arnica-io/dependency-scan@ab5da123065b211ff1d3b941748edb819153ea08 # v1.0.33\n```\n\nThe SHA for each release is listed on the [Releases](../../releases) page. This README is automatically updated with the latest SHA on every release.\n\n### Package Integrity\n\nAll npm packages are published with [SLSA provenance](https://docs.npmjs.com/generating-provenance-statements), providing cryptographic proof that each build originated from this repository. npm versions are immutable — once published, they cannot be modified or overwritten.\n\n### Recommended Workflow Triggers\n\nFor complete security coverage and accurate issue lifecycle tracking:\n\n- **Pull Requests**: `opened`, `synchronize` - Catches issues before merge\n- **Main/Release Branches**: `push` to `main`, `develop`, `staging`, `production`\n- **Build Pipelines**: Add to any workflow where code is built or deployed\n- **Manual Runs**: `workflow_dispatch` for on-demand scans\n\n### Where to View Reports\n\nSecurity scan results appear in multiple locations:\n\n1. **GitHub Step Summary**: Detailed findings report in the workflow run\n2. **Arnica Dashboard**: Full vulnerability management at `https://app.arnica.io`\n3. **Workflow Logs**: Console output with scan details\n4. **PR Comments** (if configured): Summary posted to pull requests\n\n### Inputs\n\n| Name | Required | Default | Description |\n| ---------------------- | :------: | --------------------------- | -------------------------------------------------------------------------- |\n| `repository-url` | Yes | | Repository URL associated with the scan |\n| `branch` | Yes | `main` | Branch to associate with the scan |\n| `scan-path` | No | `.` | Directory path to scan and generate SBOM for (e.g., `.` or `services/api`) |\n| `api-base-url` | No | `https://api.app.arnica.io` | Arnica API base URL |\n| `api-token` | No | | Arnica API token; prefer secret env `ARNICA_API_TOKEN` |\n| `scan-timeout-seconds` | No | `900` | Timeout (seconds) to wait for scan completion |\n| `on-findings` | No | `fail` | Behavior when findings are detected: fail, alert, or pass |\n| `debug` | No | `false` | Enable verbose API response debug logs |\n\n### Outputs\n\n- **scan-id**: Arnica scan identifier.\n- **status**: Final status, one of `Success`, `Failure`, `Error`, `Skipped`, or `Timeout`.\n\n### CLI Environment Variables (All Platforms)\n\nUse these env vars when running the scanner via `npx @arnica-io/dependency-scan` (Azure DevOps, Bitbucket Pipelines, and similar CI).\n\n| Name | Required | Default | Description |\n| ----------------------------- | :------: | --------------------------- | ---------------------------------------- |\n| `ARNICA_API_TOKEN` | Yes | | Arnica API token |\n| `ARNICA_API_BASE_URL` | No | `https://api.app.arnica.io` | Arnica API base URL |\n| `ARNICA_REPOSITORY_URL` | No | auto-detected | Repository URL override |\n| `ARNICA_BRANCH` | No | auto-detected | Branch override |\n| `ARNICA_SCAN_PATH` | No | `.` | Directory path to scan |\n| `ARNICA_SCAN_TIMEOUT_SECONDS` | No | `900` | Scan wait timeout in seconds |\n| `ARNICA_ON_FINDINGS` | No | `fail` | `fail`, `alert`, or `pass` |\n| `ARNICA_DEBUG` | No | `false` | Verbose API debug logs when set to `true`|\n\nGeneric `DEBUG` is intentionally ignored so unrelated tools that set `DEBUG=true` do not enable Arnica verbose logging.\n\nAuto-detection sources when `ARNICA_REPOSITORY_URL` / `ARNICA_BRANCH` are not provided:\n\n- **GitHub**: `GITHUB_SERVER_URL`, `GITHUB_REPOSITORY`, `GITHUB_HEAD_REF` / `GITHUB_REF_NAME`\n- **Azure DevOps**: `BUILD_REPOSITORY_URI`, `BUILD_SOURCEBRANCHNAME`\n- **Bitbucket Cloud/Server**: `BITBUCKET_GIT_HTTP_ORIGIN`, `BITBUCKET_GIT_SSH_ORIGIN`, `BITBUCKET_REPO_FULL_NAME`, `BITBUCKET_WORKSPACE`, `BITBUCKET_REPO_OWNER`, `BITBUCKET_REPO_SLUG`, `BITBUCKET_BRANCH`, `BITBUCKET_PR_SOURCE_BRANCH`, `BITBUCKET_SOURCE_BRANCH`, `BITBUCKET_BRANCH_NAME`\n- **Bitbucket Server (HTTPS clone URL synthesis):** `BITBUCKET_SERVER_URL` or `BITBUCKET_BASE_URL` with `BITBUCKET_REPO_FULL_NAME`; optional `BITBUCKET_SERVER_SCM_PREFIX` (default `scm`) when the Git HTTP path is not `/scm/...`\n- **GitLab CI**: `CI_REPOSITORY_URL` (credentials are stripped automatically), `CI_PROJECT_URL`, `CI_COMMIT_BRANCH`, `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`, `CI_COMMIT_REF_NAME` (skipped when `CI_COMMIT_TAG` is set to avoid reporting tags as branches), `CI_DEFAULT_BRANCH` (used as fallback in tag pipelines)\n\n### Permissions\n\nThis action does not require repository write permissions. For least privilege, set:\n\n```yaml\npermissions:\n contents: read\n```\n\n### Examples\n\nScan a subdirectory and alert (do not fail) on policy violations:\n\n```yaml\n- name: Generate SBOM and scan with Arnica\n id: arnica\n uses: arnica-io/dependency-scan@ab5da123065b211ff1d3b941748edb819153ea08 # v1.0.33\n env:\n ARNICA_API_TOKEN: ${{ secrets.ARNICA_API_TOKEN }}\n with:\n repository-url: https://github.com/owner/repo\n branch: ${{ github.ref_name }}\n scan-path: services/payments\n on-findings: alert\n```\n\n### Prerequisites\n\n- Sign in to Arnica with a privileged `admin` account. Sign in at `https://app.arnica.io`.\n\n### API key and permissions\n\nCreate an Arnica API key with only the SBOM scopes:\n\n1. Navigate to Admin → API.\n2. Create a new API key.\n3. Select scopes: `sbom-api:read` and `sbom-api:write` only.\n4. Store the token as a repository secret named `ARNICA_API_TOKEN`.\n\n---\n\n## Azure DevOps Pipelines\n\nUse the **published npm package** from the registry (`npx`). You only need `checkout: self` and a Node task—no extra GitHub service connection for the default flow.\n\n### Prerequisites\n\n1. **ARNICA_API_TOKEN**: Store in a **Variable Group** (e.g. `arnica-secrets` under **Pipelines → Library**) as a secret.\n2. **Node.js 24+** on the agent (`NodeTool@0`).\n\n### Example pipeline\n\n```yaml\ntrigger:\n branches:\n include:\n - main\n\npool:\n vmImage: ubuntu-latest\n\nvariables:\n - group: arnica-secrets\n\nsteps:\n - checkout: self\n\n - task: NodeTool@0\n inputs:\n versionSpec: \"24.x\"\n displayName: Use Node 24\n\n - script: |\n set -euo pipefail\n cd \"$(Build.SourcesDirectory)\"\n npx --yes \"@arnica-io/dependency-scan@1.0.33\"\n displayName: Arnica dependency scan\n env:\n ARNICA_API_TOKEN: $(ARNICA_API_TOKEN)\n```\n\nPin the version in the `npx` argument (`@x.y.z`). This README is updated with current pins on each release.\n\n### Self-hosted agent note (`npm.pkg.github.com` / 401)\n\nIf your Azure DevOps self-hosted agent has a global/user `.npmrc` that maps `@arnica-io` to GitHub Packages, `npx` may fail with `401 Unauthorized` against `npm.pkg.github.com`.\n\nForce npmjs for this step:\n\n```yaml\n - script: |\n set -euo pipefail\n cd \"$(Build.SourcesDirectory)\"\n npm config set registry \"https://registry.npmjs.org/\"\n npm config delete @arnica-io:registry || true\n npx --registry \"https://registry.npmjs.org/\" --yes \"@arnica-io/dependency-scan@1.0.33\"\n displayName: Arnica dependency scan\n```\n\n### Advanced: build from a git checkout (lockfile-pinned)\n\nIf you want transitives fixed to this repo’s `pnpm-lock.yaml`, add a **GitHub service connection**, check out `arnica-io/dependency-scan` at a release tag, then `corepack prepare pnpm@9.15.4 --activate`, `pnpm install --frozen-lockfile`, `pnpm run build`, and run `node dist/cli.js` with `PATH` including that checkout’s `node_modules/.bin`. Use the same CLI env vars (`ARNICA_API_TOKEN`, `ARNICA_REPOSITORY_URL`, `ARNICA_BRANCH`, `ARNICA_SCAN_PATH`, `ARNICA_ON_FINDINGS`, etc.) from `$(Build.SourcesDirectory)` for the project you are scanning (`checkout: self`).\n\nEnvironment variables are documented once in **CLI Environment Variables (All Platforms)** above.\n\n### Example: scan a subdirectory, alert only\n\nAdd to the same `env` block as the main example:\n\n```yaml\n ARNICA_SCAN_PATH: \"services/payments\"\n ARNICA_ON_FINDINGS: alert\n```\n\n### Where to View Reports (Azure DevOps)\n\n1. **Pipeline Extensions Tab**: Scan summary is uploaded as a task summary attachment\n2. **Arnica Dashboard**: Full vulnerability management at `https://app.arnica.io`\n3. **Pipeline Logs**: Console output with scan details\n\n---\n\n## Bitbucket Pipelines\n\nUse the **published npm package** with `npx`, same as Azure DevOps.\n\n- **Bitbucket Cloud**: auto-detects from `BITBUCKET_GIT_HTTP_ORIGIN` and `BITBUCKET_BRANCH`.\n- **Bitbucket Server/Data Center runners**: also supports `BITBUCKET_GIT_SSH_ORIGIN` and derives a repository URL from `BITBUCKET_SERVER_URL` + `BITBUCKET_REPO_FULL_NAME` when needed.\n\nYou can always override detection with `ARNICA_REPOSITORY_URL` and `ARNICA_BRANCH`.\n\n**Bitbucket Server URL shape:** Auto-derived URLs use `{BITBUCKET_SERVER_URL}/{BITBUCKET_SERVER_SCM_PREFIX}/{BITBUCKET_REPO_FULL_NAME}.git` with prefix defaulting to `scm` (common for Atlassian Bitbucket Server). Some installations use a different path segment (for example `git`); set `BITBUCKET_SERVER_SCM_PREFIX` to match yours. Project-key layouts, HTTP(S) proxies, or non-standard Git HTTP paths may still require setting `ARNICA_REPOSITORY_URL` explicitly.\n\n### Prerequisites\n\n1. **ARNICA_API_TOKEN**: Store as a **secured** repository variable (Repository settings → Pipelines → Repository variables).\n2. **Node.js 24+** on the step image (for example `node:24`).\n\n### Example pipeline\n\n```yaml\nimage: node:24\n\npipelines:\n default:\n - step:\n name: Arnica dependency scan\n script:\n - cd \"$BITBUCKET_CLONE_DIR\"\n - npx --yes \"@arnica-io/dependency-scan@1.0.33\"\n artifacts:\n - arnica-scan-summary.md\n - .arnica-scan-outputs.env\n```\n\nPin the version in the `npx` argument (`@x.y.z`). This README is updated with current pins on each release.\n\n### Advanced: test scanner from source before npm publish\n\nIf you want to validate unreleased changes, clone the scanner source in the pipeline, build it, and run it from source.\n\n```yaml\nimage: node:24\n\npipelines:\n default:\n - step:\n name: Arnica dependency scan (from source)\n script:\n - set -euo pipefail\n - test -n \"${ARNICA_API_TOKEN:-}\" || (echo \"ARNICA_API_TOKEN is required\" && exit 1)\n - test -n \"${ARNICA_SCAN_REPO_URL:-}\" || (echo \"ARNICA_SCAN_REPO_URL is required\" && exit 1)\n - git clone --depth 1 --branch \"${ARNICA_SCAN_REF:-main}\" \"${ARNICA_SCAN_REPO_URL}\" /tmp/dependency-scan-src\n - cd /tmp/dependency-scan-src\n - corepack enable\n - corepack prepare pnpm@9.15.4 --activate\n - pnpm install --frozen-lockfile\n - pnpm run build\n - pnpm run scan\n artifacts:\n - arnica-scan-summary.md\n - .arnica-scan-outputs.env\n```\n\nRequired variables for this mode:\n\n- `ARNICA_API_TOKEN` (secured)\n- `ARNICA_SCAN_REPO_URL` (git URL to your private/public dependency-scan fork)\n- `ARNICA_SCAN_REF` (optional branch/tag/commit; defaults to `main`)\n\n### Outputs and summary\n\nBitbucket Pipelines does not expose GitHub-style step outputs or Azure `##vso` variables. This integration:\n\n- Logs lines `ARNICA_OUTPUT =` for visibility in the build log.\n- Appends `name=value` lines to **`.arnica-scan-outputs.env`** under the clone directory (optional `source` in a later step, or keep via artifacts).\n- Writes **`arnica-scan-summary.md`** in the clone directory; list both files under `artifacts` if you want to download them.\n\nEnvironment variables are documented once in **CLI Environment Variables (All Platforms)** above.\n\nRepository URL detection fallback order:\n\n1. `BITBUCKET_GIT_HTTP_ORIGIN`\n2. `BITBUCKET_GIT_SSH_ORIGIN`\n3. `BITBUCKET_SERVER_URL` (or `BITBUCKET_BASE_URL`) + `BITBUCKET_REPO_FULL_NAME`\n4. `https://bitbucket.org/`\n\nBranch detection fallback order:\n\n1. `BITBUCKET_BRANCH`\n2. `BITBUCKET_PR_SOURCE_BRANCH`\n3. `BITBUCKET_SOURCE_BRANCH`\n4. `BITBUCKET_BRANCH_NAME`\n\n### Example: scan a subdirectory, alert only\n\nAdd to the same `script` or export env before `npx`:\n\n```yaml\n script:\n - export ARNICA_SCAN_PATH=\"services/payments\"\n - export ARNICA_ON_FINDINGS=\"alert\"\n - cd \"$BITBUCKET_CLONE_DIR\"\n - npx --yes \"@arnica-io/dependency-scan@1.0.33\"\n```\n\n### Where to View Reports (Bitbucket)\n\n1. **Build logs**: `ARNICA_OUTPUT` lines and scan progress\n2. **Artifacts**: `arnica-scan-summary.md` if declared under `artifacts`\n3. **Arnica Dashboard**: Full vulnerability management at `https://app.arnica.io`\n\n### Troubleshooting (Bitbucket)\n\n- **Repository URL is missing**\n - Set `ARNICA_REPOSITORY_URL` explicitly in the step environment.\n - Verify your runner exports one of: `BITBUCKET_GIT_HTTP_ORIGIN`, `BITBUCKET_GIT_SSH_ORIGIN`, or (`BITBUCKET_SERVER_URL` + `BITBUCKET_REPO_FULL_NAME`).\n- **Unexpected branch value in PR pipelines**\n - PR pipelines may expose multiple branch variables depending on runner type.\n - Set `ARNICA_BRANCH` explicitly if you need strict source-branch mapping.\n- **No summary/output artifacts visible**\n - Make sure `arnica-scan-summary.md` and `.arnica-scan-outputs.env` are listed under `artifacts`.\n\n---\n\n## GitLab CI\n\nUse the **published npm package** with `npx`, same as Azure DevOps and Bitbucket.\n\n- Auto-detects repository URL from `CI_REPOSITORY_URL` or `CI_PROJECT_URL` (embedded CI job tokens are stripped automatically).\n- Auto-detects branch from `CI_COMMIT_BRANCH`, `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`, or `CI_COMMIT_REF_NAME` (tag pipelines are handled — `CI_COMMIT_REF_NAME` is skipped when `CI_COMMIT_TAG` is set).\n\nYou can always override detection with `ARNICA_REPOSITORY_URL` and `ARNICA_BRANCH`.\n\n### Prerequisites\n\n1. **ARNICA_API_TOKEN**: Store as a **masked** CI/CD variable (Settings → CI/CD → Variables).\n2. **Node.js 24+** on the job image (for example `node:24`).\n\n### Example pipeline\n\n```yaml\nstages:\n - scan\n\ndependency-scan:\n stage: scan\n image: node:24\n script:\n - cd \"${CI_PROJECT_DIR}\"\n - npx --yes \"@arnica-io/dependency-scan@1.0.33\"\n artifacts:\n paths:\n - arnica-scan-summary.md\n - .arnica-scan-outputs.env\n reports:\n dotenv: .arnica-scan-outputs.env\n when: always\n expire_in: 7 days\n```\n\nPin the version in the `npx` argument (`@x.y.z`). This README is updated with current pins on each release.\n\n### Advanced: test scanner from source before npm publish\n\nIf you want to validate unreleased changes, clone the scanner source in the pipeline, build it, and run it from source.\n\n```yaml\nstages:\n - scan\n\ndependency-scan:\n stage: scan\n image: node:24\n script:\n - set -euo pipefail\n - test -n \"${ARNICA_API_TOKEN:-}\" || (echo \"ARNICA_API_TOKEN is required\" && exit 1)\n - git clone --depth 1 --branch \"${ARNICA_SCAN_REF:-main}\" \"${ARNICA_SCAN_REPO_URL}\" /tmp/dependency-scan-src\n - cd /tmp/dependency-scan-src\n - corepack enable\n - corepack prepare pnpm@9.15.4 --activate\n - pnpm install --frozen-lockfile\n - pnpm run build\n - cd \"${CI_PROJECT_DIR}\"\n - export PATH=\"/tmp/dependency-scan-src/node_modules/.bin:${PATH}\"\n - node /tmp/dependency-scan-src/dist/cli.js\n artifacts:\n paths:\n - arnica-scan-summary.md\n - .arnica-scan-outputs.env\n reports:\n dotenv: .arnica-scan-outputs.env\n when: always\n expire_in: 7 days\n```\n\nRequired variables for this mode:\n\n- `ARNICA_API_TOKEN` (masked)\n- `ARNICA_SCAN_REPO_URL` (git URL to your private/public dependency-scan fork)\n- `ARNICA_SCAN_REF` (optional branch/tag/commit; defaults to `main`)\n\n### Outputs and summary\n\nGitLab CI does not expose GitHub-style step outputs or Azure `##vso` variables. This integration:\n\n- Logs lines `ARNICA_OUTPUT =` for visibility in the job log.\n- Appends `name=value` lines to **`.arnica-scan-outputs.env`** under the project directory. Declare it as a `dotenv` report artifact so downstream jobs can consume the variables.\n- Writes **`arnica-scan-summary.md`** in the project directory; list it under `artifacts: paths` to download from the pipeline UI.\n\nEnvironment variables are documented once in **CLI Environment Variables (All Platforms)** above.\n\nRepository URL detection fallback order:\n\n1. `CI_REPOSITORY_URL` (embedded credentials stripped)\n2. `CI_PROJECT_URL`\n\nBranch detection fallback order:\n\n1. `CI_COMMIT_BRANCH`\n2. `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`\n3. `CI_COMMIT_REF_NAME` (skipped when `CI_COMMIT_TAG` is set)\n4. `CI_DEFAULT_BRANCH` (the project's default branch; used automatically in tag pipelines)\n\n### Example: scan a subdirectory, alert only\n\nAdd a `variables` block to the job:\n\n```yaml\n variables:\n ARNICA_SCAN_PATH: \"services/payments\"\n ARNICA_ON_FINDINGS: \"alert\"\n```\n\n### Where to View Reports (GitLab)\n\n1. **Job logs**: `ARNICA_OUTPUT` lines and scan progress\n2. **Artifacts**: `arnica-scan-summary.md` downloadable from the pipeline UI\n3. **Downstream variables**: `.arnica-scan-outputs.env` as a `dotenv` report artifact\n4. **Arnica Dashboard**: Full vulnerability management at `https://app.arnica.io`\n\n### Troubleshooting (GitLab)\n\n- **Repository URL is missing**\n - Set `ARNICA_REPOSITORY_URL` explicitly in the job variables.\n - Verify your runner exports `CI_REPOSITORY_URL` or `CI_PROJECT_URL`.\n- **Branch shows tag name instead of branch**\n - In tag pipelines, `CI_COMMIT_BRANCH` is unset and `CI_COMMIT_REF_NAME` contains the tag. The scanner detects `CI_COMMIT_TAG` and skips `CI_COMMIT_REF_NAME`, falling back to `CI_DEFAULT_BRANCH` (if set by the runner) then `main`. Set `ARNICA_BRANCH` explicitly if you need a specific value.\n- **No summary/output artifacts visible**\n - Make sure `arnica-scan-summary.md` and `.arnica-scan-outputs.env` are listed under `artifacts: paths`, and `.arnica-scan-outputs.env` is declared under `artifacts: reports: dotenv`.\n- **Workspace path warning (`CI_PROJECT_DIR` is unavailable)**\n - Ensure the job runs inside a proper GitLab CI runner. Custom Docker executors must export `CI_PROJECT_DIR`.\n\n---\n\n### Contributing\n\nSee `CONTRIBUTING.md` for development, testing, and release guidance. Please open an Issue first for substantial changes.\n\n### Code of Conduct\n\nThis project adheres to a Code of Conduct. By participating, you agree to uphold it. See `CODE_OF_CONDUCT.md`.\n\n### License\n\nMIT — see `LICENSE.md`.\n\n### Support\n\nQuestions or issues? Open a GitHub Issue. You can also propose enhancements via a feature request Issue or PR.\n","readmeFilename":"README.md"}
![\"Arnica\"](\"docs/images/arnica-logo.png\"){kind=logo}
\n \n