Codeward Scan — GitHub Action

Scan your repository for policy, license, vulnerability, and validation issues before merge. Codeward provides diff-aware scanning (focus only on what changed) to govern AI-assisted and human code changes with transparent, deterministic outputs (Markdown / HTML / JSON).

• Image: ghcr.io/codeward-io/scan:v0.4.0
• Action: codeward-io/scan@v0.4.0 (pin to a release)
• Binaries: Download standalone binaries for Linux, macOS, and Windows
• Documentation: https://docs.codeward.io/

Quick Start

Create a workflow at .github/workflows/codeward-io-scan.yml (minimal configuration — all inputs have defaults):

name: Codeward
on:
  pull_request:
  workflow_dispatch:

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read          # checkout
      packages: read          # pull GHCR image
      pull-requests: write    # comment on PRs
      issues: write           # (optional) create/update issues
    steps:
      - uses: codeward-io/scan@v0.4.0

The action will:

• Checkout base (main) and head (PR) automatically
• Pull the scanner image from GHCR
• Run a diff-aware scan (PR: base vs head, non-PR: current default branch)
• Produce findings and post a PR comment (if applicable)

For a fuller onboarding, see the Quick Start Guide.

Inputs

All inputs have sane defaults; override only when needed.

Input	Required	Default	Description
event	Yes	${{ github.event_name }}	Event name
repository	Yes	${{ github.repository }}	Repository
current_branch	Yes	${{ github.ref }}	Current branch
pr_number	No	${{ github.event.number }}	Pull request number
token	Yes	${{ github.token }}	GitHub token
webhook_secrets	No	—	Multiline KEY=VALUE pairs for custom webhook templates
intel_token	No	—	Codeward Intel API key (query:batch scope). Without one the scanner uses signed snapshots; with one it queries the live API
intel_mode	No	auto	api, download, local or disabled. Auto selects api when intel_token is set, download otherwise
intel_api	No	https://intel.codeward.io	Intel API base URL. Override only for self-hosted Intel
intel_required	No	true	Fail the scan when no vulnerability data could be obtained, rather than reporting clean
runtime	No	docker	docker or binary. Binary mode needs no Docker daemon and no registry login
version	No	v0.4.0	Scanner version to download in binary mode. Ignored for docker

Outputs

Output	Description
results_path	Directory containing the scan result JSON files

Binary Mode

By default the action runs the scanner as a container. Set runtime: binary to download and run the release binary instead — useful where Docker is unavailable or a registry login is undesirable:

- uses: codeward-io/scan@v0.4.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    runtime: binary

The binary is resolved for the runner's OS and architecture, verified against the release's SHA256SUMS before it is made executable, and cached by version+os+arch so repeat runs skip the download.

Supported on Linux and macOS runners, x64 and arm64. Windows runners resolve a .exe asset and the steps use shell: bash, but that path has not been exercised on windows-latest — treat it as untested rather than supported.

Intel Data Source

The scanner gets its vulnerability data from Codeward Intel. Two paths:

• Snapshots (default, no key needed). Signed per-ecosystem database segments are downloaded and queried locally. The action caches them between runs, so only the first scan on a runner pays the full download (~76 MB compressed for an npm project, ~1.2 GB on disk). Manifest signatures are verified against a key compiled into the scanner; a bad or missing signature fails the scan.
• Live API (intel_token). Queries Intel directly for the freshest data — EPSS and KEV movement within the day, unknown-package reporting. Requires a hand-issued key with the query:batch scope.

- uses: codeward-io/scan@v0.4.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    intel_token: ${{ secrets.CODEWARD_INTEL_TOKEN }}

If a scan cannot obtain vulnerability data at all — outage, expired key, blocked egress — it fails with vulnerability data unavailable instead of reporting a clean repository. Set intel_required: 'false' if you would rather have a partial scan than a red build.

Telemetry

The scanner sends no scan data back to Codeward. Its only outbound calls are fetching Intel snapshot segments (or querying the Intel API when intel_token is set), package-registry lookups to resolve licences, and your own webhook destinations. Your source code never leaves the runner.

Webhook Secrets

Pass sensitive values for custom webhooks via the webhook_secrets input. Each line is a KEY=VALUE pair exported as an environment variable available in webhook templates.

- uses: codeward-io/scan@v0.4.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    webhook_secrets: |
      SLACK_TOKEN=${{ secrets.SLACK_TOKEN }}
      JIRA_API_KEY=${{ secrets.JIRA_API_KEY }}
      PAGERDUTY_KEY=${{ secrets.PAGERDUTY_KEY }}

Secrets are parsed by the entrypoint, exported individually, and the raw value is unset — never leaked downstream. Reference them in webhook config using {{.Env.SLACK_TOKEN}}.

How It Works

• PR events: Checks out base + head, runs diff-mode (only changed items)
• Other events (push / workflow_dispatch): Scans the default branch
• Caching: Writable cache mount (/tmp/.cache) accelerates repeated scans

Configuration

Codeward is configured via a .codeward.yaml (or .codeward.json) file in your repository root. If no config file exists, sensible defaults are used.

# .codeward.yaml
vulnerability:
  - name: block-critical
    actions:
      new: block
      existing: warn
    rules:
      - field: Severity
        type: eq
        value: CRITICAL
    outputs:
      - format: markdown
        destination: "git:pr"
        fields: [VulnerabilityID, PkgName, Severity, FixedVersion]
        changes: [new]

Key Features

Security Scanning

• Vulnerability detection — CVE-based scanning with severity levels (CRITICAL/HIGH/MEDIUM/LOW) and CVSS scoring
• License detection — Multi-source resolution (SPDX, package metadata, registry lookups, GitHub API) with persistent disk cache
• Package analysis — Dependency enumeration with direct/indirect tracking and parent/child relationships
• 19 lockfile formats across 12 ecosystems — Node.js, Python, Ruby, Go, Rust, PHP, .NET, Dart, Swift, Java, Elixir, C/C++ — no external dependencies
• Codeward Intel as the vulnerability source — signed, per-ecosystem snapshots by default (no key required), or live API queries with a key. Richer than a raw CVE feed: EPSS, CISA KEV, exploit maturity, CVSS v4, OWASP categories, licence compatibility and package risk scoring. Browsable at https://intel.codeward.io

Policy Engine

• 5 policy types — Vulnerability, license, package, file validation, and PR validation
• Flexible actions — info, warn, or block per change category (new, existing, changed, removed)
• Rich rule types — eq, ne, lt, gt, contains, regex, in, exists, last_match, and more
• Conditional logic — implies operator for "If X then Y" policies
• Global & policy-level ignores — With optional expiration dates and author tracking

Diff Detection

• Diff-aware scanning — Compare base vs head to surface only what changed
• Change categories — New, removed, existing, and changed items with per-category actions
• Multi-source diff — Track changes per source path with glob pattern filtering

File & PR Validation

• File validation — JSON, YAML, TOML, env, properties files with auto-detection
• Line-level scanning — Scan individual lines for secrets/patterns with LineNumber and MatchedContent output
• Cross-file references — Validate values stay consistent across files (ref_path, ref_key, ref_type)
• Array wildcards — spec.containers.*.image with configurable match semantics (all, any, none)
• Last match rules — last_match/not_last_match with line_filter for multi-stage Dockerfile analysis
• Per-line implies — Combine implies + scan: lines for per-line "if X then Y" enforcement
• PR metadata validation — Title, body, labels, reviewers, file counts, changed files, and more
• Conditional validation — Check file content only when the file exists (implies + exists trigger)

Output & Reporting

• Multiple destinations — PR comments, GitHub issues, files, stdout/stderr, webhooks
• Multiple formats — Markdown, HTML, JSON with table/text/combined templates
• Custom webhooks — Send results to any HTTP endpoint (Slack, JIRA, PagerDuty, etc.) with template variables and secrets passthrough
• Custom templates — Load Go templates from filesystem for full output control
• GroupBy & collapse — Group results by field, collapse in PR comments

Configuration

• YAML & JSON config — Auto-discovered .codeward.yaml / .codeward.yml / .codeward.json
• Strict validation — Unknown fields rejected, enum validation, detailed error paths
• Graceful degradation — Invalid policies skipped with warnings, valid policies continue
• CLI, env vars, and config files — Hierarchical configuration with clear priority order

Ready-Made Profiles

Browse the Codeward Registry for ready-to-use policy profiles covering security, infrastructure, language-specific checks, compliance, secrets detection, and more. Drop a profile into your repo and customize as needed.

Examples

Block Critical Vulnerabilities

vulnerability:
  - name: block-critical
    actions: { new: block, existing: warn }
    rules:
      - field: Severity
        type: eq
        value: CRITICAL
    outputs:
      - format: markdown
        destination: "git:pr"
        changes: [new]

Block Copyleft Licenses

license:
  - name: block-copyleft
    actions: { new: block }
    rules:
      - field: Category
        type: eq
        value: Copyleft
    outputs:
      - format: markdown
        destination: "git:pr"
        changes: [new]

Ignore Test Directories

global:
  ignore:
    - name: Ignore test directories
      description: Skip findings from test code
      paths: ["test/**", "**/test/**", "**/*_test.go"]
      expires: "2026-12-31"

More examples: docs.codeward.io/docs/examples

Environment Variables

- uses: codeward-io/scan@v0.4.0
  env:
    CODEWARD_LOG_LEVEL: debug
    CODEWARD_LOG_SUMMARY: detailed

Variable	Description
CODEWARD_LOG_LEVEL	Log level: silent, error, warn, info, debug, trace
CODEWARD_LOG_FORMAT	Output format: text, json
CODEWARD_LOG_SUMMARY	Summary verbosity: minimal, standard, detailed
CODEWARD_CACHE_DIR	Cache directory path
CODEWARD_GITHUB_TOKEN	GitHub token for API access

See the CLI & Environment Variables reference for the complete list.

Install Dependencies (Optional)

For richer license and vulnerability detection, install dependencies before scanning. Perform manual checkouts + installs, then run the container directly:

# abbreviated — full example in docs
- uses: actions/checkout@v4
  with: { ref: "${{ github.base_ref }}", path: main }
- uses: actions/checkout@v4
  with: { ref: "${{ github.head_ref }}", path: branch }
- run: npm ci
  working-directory: main
- run: npm ci
  working-directory: branch
# then run the scanner container — see Installation docs

See GitHub Actions Installation for the full example.

Standalone Binaries

Pre-built static binaries are available for systems where Docker isn't available or desired:

OS	Architecture	Binary
Linux	amd64, arm64	codeward-scan-linux-amd64
macOS	amd64 (Intel), arm64 (Apple Silicon)	codeward-scan-darwin-arm64
Windows	amd64, arm64	codeward-scan-windows-amd64.exe

# Download, make executable, and run
curl -L -o codeward-scan \
  https://github.com/codeward-io/scan/releases/download/v0.4.0/codeward-scan-linux-amd64
chmod +x codeward-scan
./codeward-scan --config .codeward.yaml

Binaries are self-contained (static, CGO_ENABLED=0) with no runtime dependencies. Works with any CI system — see the Standalone Binary docs for GitLab CI and Azure Pipelines examples.

Requirements

• Runner: ubuntu-latest (or self-hosted with Docker)
• Permissions:
  • contents: read — checkout
  • packages: read — pull GHCR image
  • pull-requests: write — PR comments (if using git:pr)
  • issues: write — issues (if using git:issue)

Troubleshooting

Symptom	Fix
GHCR auth failures	Ensure packages: read permission; token scopes allow GHCR pull
Missing PR comment	Confirm pull-requests: write and event is pull_request
Docker unavailable	Use a runner with Docker pre-installed
Permission errors on artifacts	Container runs with host UID; ensure workspace writable

See Troubleshooting for more solutions.

Documentation

• Introduction — Overview and core philosophy
• Quick Start — Get running in 3 minutes
• Configuration — Complete config reference (YAML/JSON)
• CLI & Environment Variables — All CLI options and env vars
• Policies — Vulnerability, license, package, validation, and PR policies
• Outputs — Formats, destinations, templates, and custom webhooks
• Examples — Real-world configuration examples
• GitHub Actions — Detailed GitHub Actions setup
• Docker — Docker usage for any CI
• Standalone Binary — No Docker required, runs on Linux/macOS/Windows
• Kubernetes — Job and CronJob setup
• FAQ — Common questions
• Troubleshooting — Common issues and solutions
• Registry — Ready-to-use policy profiles for common use cases

Support

• Documentation: docs.codeward.io
• Registry: github.com/codeward-io/registry
• Issues: GitHub Issues
• Website: codeward.io

License

See LICENSE file for details.