Library Tools

This document defines the developer contract for tool configuration in config.

Goals

• Keep the schema simple and explicit.
• Run every tool in Docker.
• Require tools to write one or more JSON outputs into /outputs/.
• Support built-in defaults and local user overrides for tool inputs.

Config Shape

Tool configuration is flattened under config:

• config.policy
• config.conflicts
• config.tools
• config.cli

Config Fields

config.policy

Policy profile:

• default
• strict
• expert

config.conflicts

Conflict handling behavior:

• warn
• strict

config.tools

List of tool definitions. Each tool entry has:

• id: unique tool id.
• parser: built-in parser name.
• image: Docker image used for execution.
• command: tokenized argv command.
• env: environment variables for the tool container.
• inputs: named input mapping (ToolInputs).
• socket: whether /var/run/docker.sock is mounted.
• outputs: fixed literal /outputs/.

config.cli

Dictionary mapping CLI command names to tool ids.

Example:

• scan: default-scanner
• lint: default-linter

Validation rules:

• every tool id in config.tools must be unique.
• every config.cli target must reference an existing tool id.

ToolInputs

Each tools[].inputs.<key> entry contains:

• source: either:
• default for packaged built-in config
• a local file path
• destination: absolute path inside the container where input is mounted

Runtime Contract

1. Every tool runs in Docker.
2. Container outputs path is fixed: /outputs/.
3. Host run workspace is deterministic:
4. ./outputs/{tool-id}/{DATETIME}/
5. Host run workspace is always mounted into container as /outputs.
6. All tool outputs are written to /outputs/* inside the container.
7. inputs are resolved and mounted at destination.

Variables and Source of Truth

Supported Command Tokens

The schema validates these tokens in tool.command:

• {{inputs.<key>}}
• {{image.reference}}

Examples:

• {{inputs.trivy}} -> value from inputs.trivy.destination
• {{image.reference}} -> runtime image reference value

Complete Lifecycle

1. CLI command (for example scan) is resolved through config.cli to a tool id.
2. CLI loads the matching tool from config.tools.
3. CLI computes run directory:
4. ./outputs/{tool-id}/{DATETIME}/
5. CLI creates that run directory.
6. CLI resolves each input source:
7. default -> packaged config in the library
8. file path -> local override
9. CLI mounts each resolved input to its destination (read-only).
10. CLI mounts host run directory to container /outputs (read-write).
11. CLI mounts Docker socket if socket=true.
12. CLI renders command tokens and runs the tool container.
13. Tool writes one or more JSON files into /outputs/.
14. JSON artifacts are available on host under ./outputs/{tool-id}/{DATETIME}/.
15. Parser selected by tool.parser consumes outputs for result reporting.

Minimal Example

config:
  policy: default
  conflicts: warn
  tools:
    - id: default-scanner
      parser: trivy
      image: docker.io/aquasec/trivy:latest
      command:
        - trivy
        - image
        - --config
        - "{{inputs.trivy}}"
        - --format
        - json
        - --output
        - /outputs/scan.json
        - "{{image.reference}}"
      inputs:
        trivy:
          source: default
          destination: /config/trivy.yaml
      socket: true
      outputs: /outputs/
  cli:
    scan: default-scanner

Advanced Example

config:
  policy: strict
  conflicts: strict
  tools:
    - id: srcnet-scanner
      parser: trivy
      image: docker.io/aquasec/trivy:latest
      env:
        TRIVY_CACHE_DIR: /tmp/trivy-cache
      command:
        - trivy
        - image
        - --config
        - "{{inputs.trivy}}"
        - --format
        - json
        - --output
        - /outputs/scan.json
        - "{{image.reference}}"
      inputs:
        trivy:
          source: ./ci/trivy-srcnet.yaml
          destination: /config/trivy.yaml
        policy:
          source: ./ci/policy.yaml
          destination: /config/policy.yaml
      socket: true
      outputs: /outputs/
  cli:
    scan: srcnet-scanner