RetireJS Installation and RetireIgnore Configuration for DevSecOps Pipelines

Learn how to install RetireJS with Docker or npm, decide when to run it in a container, and create an effective retireignore.json file for clean, repeatable scans in GitLab CI/CD.

Introduction

RetireJS is a popular open‑source scanner that detects vulnerable JavaScript libraries and Node modules. In DevSecOps courses you’ll often see it used in two different ways:

1. Docker image – a self‑contained environment that can be pulled and run instantly.
2. npm package – installed directly into the build agent’s runtime.

Both approaches are valid, but each has trade‑offs in speed, reproducibility, and learning value. This article walks you through the best practices for installing RetireJS, explains why you may or may not need a dedicated container in your pipeline, and shows how to build a retireignore.json file that prevents false‑positive alerts from cluttering your reports.

1. Installing RetireJS – Docker vs. npm

When to use Docker

Typical Docker command

docker run --rm -v $(pwd):/src retirejs/retirejs \
  --outputformat json --outputpath /src/retire-report.json

The -v $(pwd):/src flag mounts the repository into the container, allowing RetireJS to scan the codebase.

When to use npm

npm installation steps

# 1️⃣ Add RetireJS as a dev dependency
npm install --save-dev retire

# 2️⃣ Run the scan (example for a GitLab job)
npx retire --outputformat json --outputpath retire-report.json

Tip: If the lab exercise explicitly asks you to use npm, follow that path. It reinforces the concept of tool installation and version management, which is valuable for real‑world DevSecOps work.

2. Running RetireJS in a CI/CD Pipeline – Do You Need a Container?

Both Docker and npm achieve the same scanning outcome; the choice hinges on speed vs. flexibility.

Preferred approach for CI/CD

• Use the Docker image when you want the fastest, most reproducible scan. The container eliminates the need to install Node or RetireJS on the runner, reducing job duration.
• Use npm when you already have a Node environment set up (e.g., a pipeline that runs other npm scripts) and you want to keep the dependency list in package.json.

Example GitLab CI job (Docker)

retirejs_scan:
  stage: test
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker pull retirejs/retirejs
    - docker run --rm -v $CI_PROJECT_DIR:/src retirejs/retirejs \
        --outputformat json --outputpath /src/retire-report.json
  artifacts:
    paths:
      - retire-report.json

Example GitLab CI job (npm)

retirejs_scan:
  stage: test
  image: node:18
  before_script:
    - npm ci          # installs all dev dependencies, including retire
  script:
    - npx retire --outputformat json --outputpath retire-report.json
  artifacts:
    paths:
      - retire-report.json

Both snippets produce a retire-report.json artifact that can be consumed by downstream security dashboards.

3. Building a retireignore.json File

A retireignore.json file tells RetireJS to skip known false positives or components that you have deliberately accepted. Here’s how to decide what belongs in it.

Step‑by‑step process

1. Run an initial scan and collect the JSON report.
2. Identify false positives – look for entries where:
   • The library version is flagged, but you have verified it is patched or not vulnerable in your context.
   • The vulnerability is a known issue with RetireJS’s detection logic (e.g., a forked library with a different name).
3. Confirm with stakeholders – discuss the findings with developers, security analysts, or product owners to ensure consensus.
4. Add the component to retireignore.json using the following schema:

{
  "ignore": [
    {
      "path": "public/js/vendor/jquery.min.js",
      "component": "jquery",
      "version": "3.5.1",
      "reason": "Patched in-house; CVE‑2020‑11022 not applicable"
    },
    {
      "path": "node_modules/some-lib",
      "component": "some-lib",
      "version": "*",
      "reason": "Library is a development‑only tool"
    }
  ]
}

5. Re‑run the scan to verify the entries are correctly ignored.

Practical example

During a scan you notice lodash 4.17.15 is reported as vulnerable, but the project uses a custom build that removes the vulnerable functions. After confirming with the team, you add:

{
  "ignore": [
    {
      "component": "lodash",
      "version": "4.17.15",
      "reason": "Custom build excludes vulnerable functions"
    }
  ]
}

Now future scans will no longer flag this entry, keeping the report focused on real risks.

4. Tips & Common Questions

Frequently asked questions

Quick checklist before committing

• [ ] Decide Docker or npm installation (avoid both).
• [ ] Verify the runner has the required runtime (Docker daemon or Node).
• [ ] Run a scan and review the JSON report.
• [ ] Discuss any flagged items with the development team.
• [ ] Add confirmed false positives to retireignore.json.
• [ ] Commit the ignore file and update CI configuration if needed.

Conclusion

RetireJS is a versatile tool for detecting vulnerable JavaScript dependencies. By selecting the appropriate installation method—Docker for speed and consistency, npm for hands‑on learning—you can integrate it smoothly into GitLab CI/CD pipelines. Properly maintaining a retireignore.json file ensures your security reports stay actionable and free from noise. Follow the steps and tips outlined above to embed RetireJS confidently in any DevSecOps workflow.