@securityjourney/aspen-connector

CI connector for SecurityJourney — integrates Guardian AI and Aspen Adapt into your security scanning pipeline. Supports GitLab CI and GitHub Actions.

This repository serves as both the source for the @securityjourney/aspen-connector npm package and the SecurityJourney/aspen-connector GitHub Action. GitLab users install via npm; GitHub users can use the action directly with uses: SecurityJourney/[email protected].

Modes

Aspen infers which mode to run from which environment variables are set — no explicit mode flag needed.

Mode A — Rewrite instructions from scan results

Runs your security scanner, sends the results to Guardian AI, and commits the updated instruction file back to the branch. Also records CWEs against the commit via Adapt.

Requires git write access. See Commit-back setup.

Mode B — Rewrite instructions from a CWE list

Same as Mode A but takes an explicit CWE list instead of a raw scan results file. Use this when your pipeline parses CWEs from scanner output directly and passes them as a JSON array.

Requires git write access. See Commit-back setup.

Mode C — Record CWEs

Records an explicit CWE list against the commit via Adapt. No instruction file update, no commit-back, no git access needed.

Mode D — Extract and record CWEs from scan results

Extracts CWEs from scanner output and records them against the commit via Adapt. No instruction file update, no commit-back, no git access needed.

To run Guardian AI without Adapt CWE recording, set ASPEN_EXCLUDE_GIT_METADATA_FIELDS=all on Modes A or B. Guardian will still rewrite and commit the instruction file; CWEs will not be recorded.

GitLab CI

Mode A — Rewrite instructions from scan results

aspen:
  image: node:22
  script:
    - git remote set-url origin "https://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
    - npx @securityjourney/[email protected]
  variables:
    ASPEN_API_TOKEN: $SECURITYJOURNEY_TOKEN
    ASPEN_SCAN_RESULTS_PATH: results.sarif
    ASPEN_INSTRUCTION_FILE_PATH: .gitlab/ai-instructions.md
    # ASPEN_SCANNER_TYPE is optional — auto-detected from scan results

Mode B — Rewrite instructions from a CWE list

aspen:
  image: node:22
  script:
    - git remote set-url origin "https://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
    - npx @securityjourney/[email protected]
  variables:
    ASPEN_API_TOKEN: $SECURITYJOURNEY_TOKEN
    ASPEN_CWES: '["CWE-79","CWE-89"]'
    ASPEN_INSTRUCTION_FILE_PATH: .gitlab/ai-instructions.md

Mode C — Record a CWE list (no instruction update)

aspen:
  image: node:22
  script:
    - npx @securityjourney/[email protected]
  variables:
    ASPEN_API_TOKEN: $SECURITYJOURNEY_TOKEN
    ASPEN_CWES: '["CWE-79","CWE-89"]'

Mode D — Extract and record CWEs from scan results

aspen:
  image: node:22
  script:
    - npx @securityjourney/[email protected]
  variables:
    ASPEN_API_TOKEN: $SECURITYJOURNEY_TOKEN
    ASPEN_SCAN_RESULTS_PATH: results.sarif

Environment variables

| Variable | Required | Default | Description | | ----------------------------------- | ---------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- | | ASPEN_API_TOKEN | Yes | — | Your SecurityJourney API token | | ASPEN_API_DOMAIN | No | api.securityjourney.com | API domain override | | ASPEN_SCAN_RESULTS_PATH | Modes A, D | — | Path to a SARIF or scanner JSON output file | | ASPEN_INSTRUCTION_FILE_PATH | Modes A, B | — | Path to an AI instruction file, or a directory containing one .md file | | ASPEN_CWES | Modes B, C | — | JSON array of CWE IDs, e.g. '["CWE-79","CWE-89"]' | | ASPEN_SCANNER_TYPE | No | auto-detected | Override scanner detection: snyk, bandit, sonarqube, semgrep, etc. | | ASPEN_AUTO_COMMIT | No | true | Set false to skip writing and committing the updated instruction file (Modes A, B) | | ASPEN_COMMIT_MESSAGE | No | auto-generated | Custom commit message for the instruction file update. [skip ci] is appended automatically if not present. | | ASPEN_EXCLUDE_GIT_METADATA_FIELDS | No | [] | all to disable CWE recording entirely, or a JSON array of fields to omit: "repo", "username", "prNumber" |

GitHub Actions

The action handles Node.js setup internally. actions/checkout must run before the action — typically already present in your workflow for the scanner step.

Mode A — Rewrite instructions from scan results

jobs:
  aspen:
    permissions:
      contents: write # required for commit-back
    steps:
      - uses: actions/checkout@v4

      - name: Run scanner
        run: snyk code test --sarif > results.sarif || true

      - uses: SecurityJourney/[email protected]
        with:
          api_token: ${{ secrets.SECURITYJOURNEY_TOKEN }}
          scan_results_path: results.sarif
          instruction_file_path: .github/ai-instructions.md
          # scanner_type is optional — auto-detected from scan results

Mode B — Rewrite instructions from a CWE list

jobs:
  aspen:
    permissions:
      contents: write # required for commit-back
    steps:
      - uses: actions/checkout@v4

      - uses: SecurityJourney/[email protected]
        with:
          api_token: ${{ secrets.SECURITYJOURNEY_TOKEN }}
          cwes: '["CWE-79","CWE-89"]'
          instruction_file_path: .github/ai-instructions.md

Mode C — Record a CWE list (no instruction update)

steps:
  - uses: actions/checkout@v4

  - uses: SecurityJourney/[email protected]
    with:
      api_token: ${{ secrets.SECURITYJOURNEY_TOKEN }}
      cwes: '["CWE-79","CWE-89"]'

Mode D — Extract and record CWEs from scan results

steps:
  - uses: actions/checkout@v4

  - name: Run scanner
    run: snyk code test --sarif > results.sarif || true

  - uses: SecurityJourney/[email protected]
    with:
      api_token: ${{ secrets.SECURITYJOURNEY_TOKEN }}
      scan_results_path: results.sarif

Commit-back setup

GitLab — CI_JOB_TOKEN

Modes A and B commit the updated instruction file back to the branch. The pipeline must configure the git remote before running aspen:

script:
  - git remote set-url origin "https://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"

CI_JOB_TOKEN requires CI/CD job token write access enabled in the project's Settings → CI/CD → Token Access. If your project does not allow this, use a project access token with write_repository scope:

script:
  - git remote set-url origin "https://aspen-bot:${PROJECT_ACCESS_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"

The connector configures git identity automatically (aspen-bot by default, or the pipeline user's identity if GITLAB_USER_EMAIL / GITLAB_USER_NAME are set).

GitHub Actions — GITHUB_TOKEN

The action uses GITHUB_TOKEN automatically — no configuration needed. Set contents: write on the job and the action handles the rest.

To override the git identity used for the commit, pass environment variables on the step:

- uses: SecurityJourney/[email protected]
  with:
    api_token: ${{ secrets.SECURITYJOURNEY_TOKEN }}
    ...
  env:
    ASPEN_GIT_USER_EMAIL: [email protected]
    ASPEN_GIT_USER_NAME: My Bot

Requirements

• Node.js 22.3.0 or later
• GitLab 15.x or later (for CI_COMMIT_COMMITTER_EMAIL)