tc-scanner

A CI security scanner for Dockerfiles, container images, dependencies, and secrets. Powered by Trivy.

Requirements

Docker is required. The scanner runs Trivy inside a container, so no additional installation is needed. All major CI platforms (Bitbucket Pipelines, GitHub Actions, GitLab CI) have Docker available by default.

Installation

No installation required. Use directly with npx:

npx tc-scanner scan ./Dockerfile

Or install globally:

npm install -g tc-scanner
tc-scan scan ./Dockerfile

Quick Start

# Scan a Dockerfile for misconfigurations
npx tc-scanner scan ./Dockerfile

# Scan project dependencies for known vulnerabilities
npx tc-scanner deps .

# Scan code for hardcoded secrets
npx tc-scanner secrets ./src

# Scan a container image
npx tc-scanner image nginx:latest

Commands

scan - Dockerfile Security

Scans Dockerfiles for security misconfigurations.

npx tc-scanner scan ./Dockerfile
npx tc-scanner scan ./Dockerfile --severity HIGH
npx tc-scanner scan ./Dockerfile --output ./reports/dockerfile-scan

What it detects:

• Running as root user
• Missing HEALTHCHECK instruction
• Using latest tag instead of pinned versions
• Insecure ADD instead of COPY
• Exposed sensitive ports
• Missing USER instruction

deps - Dependency Vulnerabilities

Scans package lockfiles for known CVEs (similar to Snyk/npm audit).

npx tc-scanner deps .
npx tc-scanner deps ./backend --severity CRITICAL
npx tc-scanner deps . --include-dev

Supported lockfiles:

• package-lock.json (npm)
• yarn.lock (Yarn)
• pnpm-lock.yaml (pnpm)
• Gemfile.lock (Ruby)
• requirements.txt / Pipfile.lock (Python)
• go.sum (Go)
• composer.lock (PHP)
• pom.xml (Maven / Java, Kotlin)

secrets - Secret Detection

Scans code for hardcoded secrets and sensitive data.

npx tc-scanner secrets .
npx tc-scanner secrets ./src --output ./reports/secrets

What it detects:

• AWS access keys and secrets
• API tokens (Stripe, GitHub, Slack, etc.)
• Private keys (RSA, SSH, PGP)
• Database connection strings
• Hardcoded passwords
• JWT secrets

image - Container Image Scanning

Scans container images for OS and application vulnerabilities.

npx tc-scanner image nginx:latest
npx tc-scanner image myapp:v1.2.3 --severity HIGH,CRITICAL

What it detects:

• OS package vulnerabilities (Alpine, Debian, Ubuntu, RHEL, etc.)
• Application dependencies inside the image
• Embedded secrets and misconfigurations

Options

| Option | Alias | Description | Default | | --------------- | ----- | ----------------------------------------------------------- | ------- | | --severity | -s | Minimum severity level: LOW, MEDIUM, HIGH, CRITICAL | HIGH | | --output | -o | Save reports to file (creates .json, .txt, .html) | - | | --webhook | -w | Send results to a webhook URL | - | | --exit-code | - | Exit code when issues are found | 1 | | --include-dev | - | Include dev dependencies (deps command only) | false |

Reports

Generate reports in multiple formats:

npx tc-scanner scan ./Dockerfile --output ./reports/scan-report

This creates:

• scan-report.json - Structured data for APIs and integrations
• scan-report.txt - Plain text for email notifications
• scan-report.html - Styled HTML report for attachments

Webhooks

Send scan results to any webhook endpoint:

# Generic webhook
npx tc-scanner scan ./Dockerfile --webhook https://your-api.com/security-alerts

# Slack incoming webhook
npx tc-scanner scan ./Dockerfile --webhook https://hooks.slack.com/services/xxx/yyy/zzz

Webhook payload:

{
  "scanner": "tc-scanner",
  "scanType": "dockerfile",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "target": "./Dockerfile",
  "summary": {
    "total": 3,
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 0
  },
  "issues": [
    {
      "id": "DS-0002",
      "severity": "HIGH",
      "title": "Last USER command should not be 'root'",
      "description": "Running containers with 'root' user can lead to container escape.",
      "url": "https://avd.aquasec.com/misconfig/ds-0002"
    }
  ]
}

CI/CD Integration

Bitbucket Pipelines

image: node:20

definitions:
  services:
    docker:
      memory: 2048

pipelines:
  default:
    - step:
        name: Security Scan
        services:
          - docker
        script:
          - npx tc-scanner scan ./Dockerfile --severity HIGH
          - npx tc-scanner deps . --severity HIGH
          # Send results to Slack or custom webhook
          - npx tc-scanner scan ./Dockerfile --webhook $SECURITY_WEBHOOK_URL --exit-code 0

  pull-requests:
    "**":
      - step:
          name: PR Security Check
          services:
            - docker
          script:
            - npx tc-scanner scan ./Dockerfile --severity CRITICAL
            - npx tc-scanner secrets ./src

Note: Add SECURITY_WEBHOOK_URL as a repository variable in Bitbucket settings for webhook notifications.

Bitbucket Pipelines — Java / Maven (Kotlin)

image: eclipse-temurin:17

definitions:
  services:
    docker:
      memory: 2048

pipelines:
  default:
    - step:
        name: TC-Secure Controls (Maven)
        services:
          - docker
        caches:
          - maven
        script:
          # Auto-detects maven stack from pom.xml and runs all 5 controls
          - npx tc-scanner controls .
            --base-url $TC_ADMIN_BASE_URL
            --api-key  $SERVICE_API_KEY
            --client-name $CLIENT_NAME

  pull-requests:
    "**":
      - step:
          name: PR Security Check (Maven)
          services:
            - docker
          caches:
            - maven
          script:
            - npx tc-scanner controls . --controls 1,2,3 --dry-run

JaCoCo coverage: to get real line-coverage numbers in control 7, add the JaCoCo Maven plugin to your pom.xml and run ./mvnw verify instead of ./mvnw test so that target/site/jacoco/jacoco.xml is generated before the scanner reads it.

GitHub Actions

name: Security Scan

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan Dockerfile
        run: npx tc-scanner scan ./Dockerfile --severity HIGH

      - name: Scan Dependencies
        run: npx tc-scanner deps . --severity HIGH

      - name: Scan for Secrets
        run: npx tc-scanner secrets ./src

GitLab CI

security-scan:
  image: node:20
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
  script:
    - npx tc-scanner scan ./Dockerfile --severity HIGH
    - npx tc-scanner deps . --severity HIGH
    - npx tc-scanner secrets ./src
  artifacts:
    paths:
      - reports/
    when: always

Controls Platform Integration (tc-admin)

For normalized control ingestion into tc-admin, use:

• emitter script: ./scripts/emit-check-run.mjs
• pipeline template: ./examples/bitbucket-pipelines.controls.example.yml

Required CI variables:

• TC_ADMIN_BASE_URL (example: https://tc-admin.internal)
• SERVICE_API_KEY (shared ingest key)
• CLIENT_NAME (tenant/client label)

Quality-gate readiness check:

# Human-readable readiness output
npx tc-scanner quality-gate . --ci-provider bitbucket

# JSON output for automation
npx tc-scanner quality-gate . --ci-provider bitbucket --json

# Fail CI when gate is not enabled
npx tc-scanner quality-gate . --ci-provider bitbucket --strict

The check inspects:

• Presence of bitbucket-pipelines.yml
• Control pipeline signals (e.g. tc-scan controls, emit script, scan/test commands)
• Required ingestion env vars (TC_ADMIN_BASE_URL, SERVICE_API_KEY, CLIENT_NAME)

The template posts these control codes:

• SEC_DEP_PATCH
• SEC_CONTAINER_VULN
• SEC_SECRETS
• CODE_STATIC
• QA_TESTS

Supported stacks (auto-detected from project files):

| Stack | Detected by | Control 1 | Control 4 | Control 7 | | -------- | ------------------------------------ | ------------------------- | --------------------------- | ------------------------------------- | | node | package.json, lockfiles | npm/pnpm audit | lint/typecheck scripts | test script + coverage-summary.json | | python | requirements.txt, pyproject.toml | pip-audit | ruff/pyright/mypy | pytest | | php | composer.json | composer audit | composer run lint/phpstan | composer run test | | maven | pom.xml | Trivy filesystem CVE scan | ./mvnw test-compile | ./mvnw test + Surefire + JaCoCo |

Force a specific stack with --stack maven if auto-detection is ambiguous.

Maven / Java / Kotlin notes:

• Control 1 uses Trivy's filesystem scanner to match pom.xml dependencies against the CVE database — no Maven execution needed. If native trivy is unavailable, the scanner automatically falls back to Docker-based Trivy.
• Control 3 (Secrets) runs a repository scan first; for Maven projects with a pom.xml, it also performs a focused pom.xml secret scan when the repository-level result is empty.
• Control 4 runs ./mvnw test-compile -B -q (falls back to system mvn if no wrapper is present). Compile errors are reported as lint_errors.
• You can override Control 4 for Maven in _tc-scan.config.json with controls.static.lint_command (and optional controls.static.cwd) to run project-specific quality goals.
• Control 7 runs ./mvnw test -B and parses target/surefire-reports/TEST-*.xml for accurate pass/fail counts. Line coverage is read from target/site/jacoco/jacoco.xml when present (requires the JaCoCo Maven plugin); otherwise coverage_pct falls back to pass_rate_pct.
• The Maven wrapper (mvnw) is preferred over a system-installed mvn when present in the project root.

Exit Codes

| Code | Meaning | | ---- | --------------------------------------------- | | 0 | No issues found (or below severity threshold) | | 1 | Issues found at or above severity threshold |

Use --exit-code 0 to always pass (useful for non-blocking scans):

npx tc-scanner scan ./Dockerfile --exit-code 0

Severity Levels

| Level | Description | | ---------- | --------------------------------------------------- | | CRITICAL | Severe vulnerabilities requiring immediate action | | HIGH | Important security issues that should be fixed soon | | MEDIUM | Moderate issues to address in regular maintenance | | LOW | Minor issues or best practice recommendations |

Examples

Fail CI only on critical issues:

npx tc-scanner scan ./Dockerfile --severity CRITICAL

Full security audit with reports:

npx tc-scanner scan ./Dockerfile --output ./reports/dockerfile --severity LOW
npx tc-scanner deps . --output ./reports/deps --severity LOW --include-dev
npx tc-scanner secrets ./src --output ./reports/secrets

Send alerts to Slack on failures:

npx tc-scanner scan ./Dockerfile --webhook $SLACK_WEBHOOK_URL

Troubleshooting

"Docker is required"

• Ensure Docker is installed and running
• In CI, enable the Docker service (see examples above)

"No lockfile found" (deps command)

• The scanner needs package-lock.json, yarn.lock, pom.xml, or similar
• Run npm install (Node) or ensure pom.xml is present (Maven) to enable scanning

Maven build fails during control 4 or 7

• Ensure JDK 17+ is available in the CI image (e.g. eclipse-temurin:17)
• The scanner prefers ./mvnw over a system mvn; commit the Maven wrapper to your repo
• For coverage data, add the JaCoCo plugin and run ./mvnw verify to produce target/site/jacoco/jacoco.xml

Slow first run

• First run downloads the Trivy Docker image (~50MB) and vulnerability database (~80MB)
• Subsequent runs are faster due to caching