containerlint

intent

containerlint scans codebases for docker and container security anti-patterns using regex-based pattern matching across 90 container-specific checks (dockerfile best practices, security context, health checks, resource limits, networking, orchestration). runs 100% locally with zero telemetry. use this when you need to audit dockerfile quality, detect privileged containers, find missing health checks, identify resource limit gaps, or validate docker-compose configurations before deploying to production.

inputs

required binaries:

• git (v2.0+)
• bash (v4.0+)
• python3 (v3.6+)
• jq (v1.6+)
• lefthook (optional, only for git hook integration; install via brew install lefthook or included in skill metadata)

environment variables:

• CONTAINERLINT_LICENSE_KEY (optional, required only for Pro and Team tier scans)
  • free tier: works without license
  • pro tier ($19/user/month): validate with this key
  • team tier ($39/user/month): validate team license
  • enterprise: contact support

configuration file:

• location: ~/.openclaw/openclaw.json
• schema:

  {
    "skills": {
      "entries": {
        "containerlint": {
          "enabled": true,
          "apiKey": "YOUR_LICENSE_KEY",
          "config": {
            "severityThreshold": "medium",
            "ignorePatterns": ["**/test/**", "**/fixtures/**"],
            "ignoreChecks": [],
            "reportFormat": "text"
          }
        }
      }
    }
  }
  

• all fields optional; defaults are permissive

external connections:

• none. all pattern matching is local. license validation is offline (no network calls).

target input:

• file path or directory path (defaults to current working directory)
• supports: Dockerfile, docker-compose.yml, docker-compose.yaml, .yml/.yaml with container config, any text file

procedure

step 1: validate environment and tier

input: CONTAINERLINT_LICENSE_KEY env var (if scanning pro/team tier) output: tier determination (free/pro/team), license status (valid/invalid/expired)

1. check if CONTAINERLINT_LICENSE_KEY is set
2. if set, validate key format and expiry offline
3. if key invalid or expired, print error message with link to https://containerlint.pages.dev/renew and exit code 1
4. if no key, default to free tier (30 patterns, DF and SC categories only)
5. if valid key, determine tier level from key metadata and allow corresponding pattern access

step 2: discover scannable files

input: target path (file or directory) output: list of scannable files, file count

1. if target is file, add to scannable list if not binary
2. if target is directory, recursively find all files
3. skip directories: .git, node_modules, .env, vendor, dist, build, .next, pycache, .venv
4. skip binary files: .png, .jpg, .jpeg, .gif, .ico, .zip, .tar, .gz, .bin, .so, .o, .pyc, .class
5. skip minified js: *.min.js
6. collect remaining files
7. if no files found, report "no scannable files in target directory" and exit code 0 (clean scan)

step 3: apply ignore patterns and checks

input: discovered files, ignorePatterns and ignoreChecks from config output: final list of files to scan

1. read config from ~/.openclaw/openclaw.json if present
2. extract ignorePatterns array (glob-style paths to exclude)
3. extract ignoreChecks array (check IDs to skip globally)
4. filter discovered files against ignorePatterns using bash globbing
5. pass both filtered file list and ignoreChecks to pattern matching step

step 4: run pattern matching

input: filtered file list, tier (free/pro/team), category filter (optional), ignoreChecks list output: raw findings (file, line number, check ID, severity, description, recommendation)

1. load pattern definitions based on tier
   • free tier: 30 patterns (DF: 15, SC: 15)
   • pro tier: 60 patterns (DF: 15, SC: 15, HC: 15, RS: 15)
   • team tier: 90 patterns (DF: 15, SC: 15, HC: 15, RS: 15, NW: 15, OR: 15)
2. if --category flag used, filter patterns to requested category only
3. for each file in filtered list: a. read file contents b. for each pattern in allowed set: i. skip if check ID in ignoreChecks ii. run regex match against file iii. capture line number(s) of match iv. record: file path, line number, check ID, severity, description, remediation text
4. return all findings in order (by file, then by line, then by check ID)

step 5: calculate security score

input: all findings, severity counts output: numeric score (0-100), grade (A-F), per-file scores

1. initialize score to 100
2. for each critical finding: deduct 25 points
3. for each high finding: deduct 15 points
4. for each medium finding: deduct 8 points
5. for each low finding: deduct 3 points
6. floor score at 0 (no negative scores)
7. calculate per-file score using same logic
8. assign grade: A (90-100), B (80-89), C (70-79), D (60-69), F (<60)
9. determine pass/fail: score >= 70 = pass (exit code 0), score < 70 = fail (exit code 1)

step 6: format output

input: findings, score, grade, format flag (text/json/html), verbose flag output: formatted report (text, json, or html)

text format (default):

containerLint Security Audit
=============================
Target: [path]
Tier: [free/pro/team]
Scan Date: [ISO 8601]

SCORE: [85] / 100 (Grade: B)

Findings: [12 total] [0 critical] [3 high] [6 medium] [3 low]

[file1.Dockerfile]
  Line 5: DF-001 [HIGH] Missing USER directive
  Remediation: Add 'USER appuser' before CMD
  
  Line 12: SC-003 [CRITICAL] Running as root
  Remediation: Create unprivileged user and set with USER directive

[file2.docker-compose.yml]
  Line 8: RS-002 [MEDIUM] No memory limit defined
  Remediation: Add 'mem_limit: 512m' to service config

=============================
Summary:
  Pass threshold: 70
  Your score: 85
  Status: PASS (exit code 0)

json format:

{
  "scan": {
    "target": "/path/to/target",
    "tier": "pro",
    "timestamp": "2024-01-15T10:30:00Z",
    "score": 85,
    "grade": "B",
    "pass": true,
    "findings": [
      {
        "file": "Dockerfile",
        "line": 5,
        "checkId": "DF-001",
        "severity": "high",
        "description": "Missing USER directive",
        "remediation": "Add 'USER appuser' before CMD"
      }
    ],
    "summary": {
      "total": 12,
      "critical": 0,
      "high": 3,
      "medium": 6,
      "low": 3
    }
  }
}

html format:

• generate standalone html file with inline css
• include clickable file links, severity color coding (red for critical, orange for high, yellow for medium, gray for low)
• show score gauge, per-file summary table, detail findings with line numbers as anchors

1. if --verbose flag, include full pattern regex and matched line text in output
2. if --format json, output valid json to stdout
3. if --format html, write html to containerlint-report.html in current directory
4. default to text format to stdout

step 7: exit with appropriate code

input: pass/fail determination from step 5 output: exit code (0 or 1)

1. if score >= 70, exit 0 (pass)
2. if score < 70, exit 1 (fail)

decision points

if tier is free:

• allow only 30 patterns (DF and SC categories)
• if user requests pro/team features with --tier pro or --tier team but no valid license, print error: "pro/team tier requires valid license key. set CONTAINERLINT_LICENSE_KEY and retry" and exit code 1

if license key is invalid or expired:

• print error: "license key invalid or expired. renew at https://containerlint.pages.dev/renew"
• exit code 1
• fall back to free tier if key is absent (no error)

if category filter is used:

• if category is invalid (not one of DF, SC, HC, RS, NW, OR), print available categories and exit code 1
• if category is valid, run only patterns in that category (tier still limits access, e.g. pro tier cannot access NW or OR)

if target is empty directory (no scannable files):

• report "no scannable files found in target"
• return clean scan (score 100, grade A, zero findings)
• exit code 0

if lefthook is requested for git hooks but not installed:

• print message: "lefthook not found. install via 'brew install lefthook' or see https://containerlint.pages.dev/install"
• do not fail the scan; only fail the hook installation step

if file is binary:

• skip silently with no warning

if a specific file cannot be read (permission denied, etc.):

• print warning: "skipped [filename]: permission denied"
• continue scanning other files
• do not fail the scan

if verbose mode is enabled:

• include matched line text and full pattern regex in every finding detail
• useful for debugging why a pattern matched

if ignoreChecks contains a check ID that does not exist:

• silently ignore the invalid check ID (do not warn)
• proceed with scan

output contract

required formats:

1. text format (default):

   • stdout stream with human-readable report
   • sections: header, score/grade, findings grouped by file, summary
   • each finding shows: file path, line number, check ID, severity, description, remediation
   • footer shows pass/fail status and exit code logic

2. json format:

   • valid json (parseable by jq)
   • schema: { scan: { target, tier, timestamp, score, grade, pass, findings: [], summary: {} } }
   • all timestamps in iso 8601 format
   • all severity values lowercase: critical, high, medium, low

3. html format:

   • standalone file: containerlint-report.html written to current directory
   • self-contained (inline css, no external assets)
   • responsive design, readable on desktop and mobile
   • severity color coding (red/orange/yellow/gray)
   • clickable file links within report

file locations:

• config read from: ~/.openclaw/openclaw.json (optional)
• html report written to: containerlint-report.html (if --format html)
• all other output to stdout

exit codes:

• 0: scan completed, score >= 70 (pass)
• 1: scan completed, score < 70 (fail) OR error (invalid license, bad input, etc.)

data invariants:

• score is integer from 0-100
• grade is single character: A, B, C, D, or F
• check ID format: [DF|SC|HC|RS|NW|OR]-\d{3} (e.g. DF-001)
• severity is one of: critical, high, medium, low
• line numbers are positive integers (1-indexed)
• all file paths are absolute or relative to cwd

outcome signal

the user knows the skill worked when:

1. text output appears immediately showing score, grade, findings grouped by file with line numbers
2. json is valid and parseable by jq (test: containerlint scan . --format json | jq .)
3. html report is generated at containerlint-report.html with clickable findings
4. exit code matches expectation: run containerlint scan . && echo "PASS" || echo "FAIL" and see PASS or FAIL printed
5. findings match reality: scan detects known anti-patterns (e.g. FROM ... as root triggers SC-003, missing HEALTHCHECK triggers HC-001)
6. per-file scores are visible and can be used to identify worst offenders
7. remediation text is actionable (e.g. "Add USER directive before CMD" is specific and copy-paste ready)
8. ignored patterns are respected: if config contains ignorePatterns, files matching those globs are not scanned
9. tier features work as advertised: free tier scans 30 patterns, pro adds 30 more, team adds final 30
10. license validation is fast (offline, no network lag)