Docker Installation

Run Codeward via Docker for a consistent, reproducible scanning environment across any CI system (GitHub Actions, GitLab, Jenkins, local dev).

---

Quickest Start (Minimal)

Scan a repository with default settings — just mount your repo:

docker run --rm \
  -v /path/to/your/repo:/main:rw \
  ghcr.io/codeward-io/scan:latest

That's it. Results go to stdout with default policies.

---

Fast Repeated Scans with Cache

Add a persistent cache to speed up subsequent scans (Trivy database downloads once):

mkdir -p cache

docker run --rm \
  -v /path/to/your/repo:/main:rw \
  -v $(pwd)/cache:/.cache:rw \
  ghcr.io/codeward-io/scan:latest

First run downloads the vulnerability database (~30s). Subsequent runs use the cache (~5s).

---

PR Diff Scan (Compare Branches)

Compare a feature branch against main to see only what changed:

mkdir -p cache

docker run --rm \
  -v /path/to/main-branch:/main:rw \
  -v /path/to/feature-branch:/branch:rw \
  -v $(pwd)/cache:/.cache:rw \
  -e CODEWARD_MODE=diff \
  ghcr.io/codeward-io/scan:latest

Results are categorized as new, changed, removed, or existing.

---

Full Example with GitHub Integration

Post results to a PR comment and create issues:

mkdir -p cache

docker run --rm \
  -v /path/to/main-branch:/main:rw \
  -v /path/to/feature-branch:/branch:rw \
  -v $(pwd)/cache:/.cache:rw \
  -e CODEWARD_MODE=diff \
  -e CODEWARD_GITHUB_TOKEN=$GITHUB_TOKEN \
  -e CODEWARD_GITHUB_OWNER=myorg \
  -e CODEWARD_GITHUB_REPOSITORY=myrepo \
  -e CODEWARD_GITHUB_PR_NUMBER=123 \
  ghcr.io/codeward-io/scan:latest

---

Complete Example with All Options

Every configurable option in one command:

mkdir -p results cache

docker run --rm \
  -v /path/to/main-branch:/main:rw \
  -v /path/to/feature-branch:/branch:rw \
  -v $(pwd)/cache:/.cache:rw \
  -v $(pwd)/results:/.results:rw \
  -v $(pwd)/.codeward.json:/config/config.json:ro \
  -v $(pwd)/private.json:/config/private.json:ro \
  -e CODEWARD_MODE=diff \
  -e CODEWARD_CONFIG_PATH=/config/config.json \
  -e CODEWARD_PRIVATE_CONFIG_PATH=/config/private.json \
  -e CODEWARD_GITHUB_TOKEN=$GITHUB_TOKEN \
  -e CODEWARD_GITHUB_OWNER=myorg \
  -e CODEWARD_GITHUB_REPOSITORY=myrepo \
  -e CODEWARD_GITHUB_PR_NUMBER=123 \
  -e CODEWARD_API=https://api.codeward.io \
  ghcr.io/codeward-io/scan:latest

---

Environment Variables Reference

Core Settings

Variable	Required	Default	Description
CODEWARD_MODE	No	main	Scan mode: diff for branch comparison, main for single-branch scan

GitHub Integration

Required only when using git:pr or git:issue output destinations.

Variable	Required For	Description
CODEWARD_GITHUB_TOKEN	git:pr, git:issue	GitHub API token with appropriate permissions
CODEWARD_GITHUB_OWNER	git:pr, git:issue	Repository owner or organization name
CODEWARD_GITHUB_REPOSITORY	git:pr, git:issue	Repository name
CODEWARD_GITHUB_PR_NUMBER	git:pr	Pull request number (only for diff mode)

Token permissions needed:

• pull-requests: write — for posting PR comments
• issues: write — for creating/updating issues

Configuration Overrides

Variable	Required	Default	Description
CODEWARD_CONFIG_PATH	No	.codeward.json in repo	Path to primary configuration file
CODEWARD_PRIVATE_CONFIG_PATH	No	—	Path to private config (merged with primary)

---

Volume Mounts Reference

Container Path	Purpose	Required
/main	Main/base branch checkout	Yes
/branch	Feature branch checkout	Only for CODEWARD_MODE=diff
/results	Output directory for file-based reports	Suggested if using file: destinations
/.cache	Trivy database and scan cache	Recommended for performance

---

Image Versions

Tag	Use Case
latest	Quick experiments, always latest
v0.2.0	Production use, pinned version

Recommendation: Pin to a specific version in CI pipelines for reproducibility.

ghcr.io/codeward-io/scan:v0.2.0

---

Performance Tips

1. Use persistent cache — Mount a host directory to /.cache to avoid re-downloading the vulnerability database
2. Install dependencies first — Run npm ci, pip install, etc. before scanning for better transitive dependency detection
3. Limit output fields — Only include fields you need in your config
4. Pin image versions — Avoid unexpected changes in CI

---

Troubleshooting

Symptom	Cause	Fix
Permission denied writing results	Host directory not writable	chmod 777 results/ or adjust ownership
Cache not reused between runs	Ephemeral cache path	Mount a persistent host directory to /.cache
Everything marked as "new"	Missing baseline	Mount main branch at /main and set CODEWARD_MODE=diff
No PR comment posted	Missing GitHub env vars	Set all CODEWARD_GITHUB_* variables
Empty output	No findings match policy	Check changes filter includes new

See Troubleshooting for more solutions.

---

Example Configuration

Minimal policy that blocks critical vulnerabilities and saves results:

{
  "vulnerability": [{
    "name": "block-critical",
    "actions": { "new": "block", "existing": "warn" },
    "rules": [
      { "field": "Severity", "type": "eq", "value": "CRITICAL" }
    ],
    "outputs": [
      {
        "format": "markdown",
        "destination": "file:/results/vulnerabilities.md",
        "fields": ["VulnerabilityID", "PkgName", "Severity", "FixedVersion"],
        "changes": ["new"]
      },
      {
        "format": "json",
        "destination": "file:/results/vulnerabilities.json"
      }
    ]
  }]
}

Save as .codeward.json in your repo root, or mount it with CODEWARD_CONFIG_PATH.

---

Security Notes

• Use repository-scoped tokens, not personal access tokens
• Treat config files as sensitive (policy logic may reveal security criteria)
• Avoid passing untrusted input to configuration

---

Related

• GitHub Actions — Simplified setup for GitHub
• Configuration — Full config reference
• Policies — All policy types explained
• Outputs — Formats and destinations