Traceable CLI

Traceable CLI 2.0 is a command-line interface for configuring, running, and managing API security scans. It provides a file-based configuration system that allows you to define runners, scan parameters, and logging preferences through a YAML file.

The CLI acts as an interface between your environment and the Traceable platform, enabling automated scan execution, flexible configuration management, and enhanced observability through logging.

Traceable home directory

The traceable_home directory is the central workspace for the Traceable CLI. It contains the configuration files, logs, credentials, and scan data. The following table highlights the files within the directory and their descriptions:

This directory and file-based model ensures that all operational and diagnostic information is stored in a single, organized location.

CLI configuration model

The CLI uses a YAML-based configuration file that defines the operational behavior of scan execution. This structure enables you to configure scan scope, logging levels, and performance parameters.

Traceable uses two configuration files:

These files are available under the traceable_home directory, which also acts as the storage location for all scan and log-related data.

YAML structure

The CLI configuration file contains multiple sections, each defining a distinct area of the CLI functionality. The following YAML structure highlights the different configurations in the config.yaml file, and comments alongside each configuration, defining its functionality:

runner:
  runner_name:   # Name of the Traceable CLI runner
  heartbeat: 
    interval:   # Frequency of runner heartbeat in seconds <default: 5 secs>
  advanced:
    runner_labels:   # Comma-separated list of labels for the runner
clients:
  user_agent:   # User agent to use while sending requests
  ast:
    http:
      request_timeout_seconds:   # Request timeout in seconds <default: 10 secs>
      domain_mappings:
      - pattern: *.traceable.ai*   # Pattern
        proxy: 
          host_name:   # Proxy hostname
          port:   # Proxy port
          user_name:   # Proxy user_name
          password:   # Proxy password
        tls:
          root_ca_file:   # Path to the root_ca file
          host:   # Hostname (CN), this certificate should be used for
          client_cert_file:   # Path to the client certificate PEM file
          client_key_file:   # Path to the client’s private-key PEM file
          client_key_passphrase:   # String passphrase needed to decrypt the private key
      - pattern: *customer_http_domain.com*
        proxy:
          host_name:   # Proxy hostname
          port:   # Proxy port
          user_name:   # Proxy user_name
          password:   # Proxy password
        tls:
          root_ca_file:   # Path to the root_ca file
          host:   # Hostname (CN), this certificate should be used for
          client_cert_file:   # Path to the client certificate PEM file
          client_key_file:   # Path to the client’s private-key PEM file
          client_key_passphrase:   # String passphrase needed to decrypt the private key
    grpc:
      no_verify:   # If true, uses an insecure GRPC channel <default: False>
      timeout:   # Timeout for the GRPC method calls
      enable_retries:   # To enable retries
      retry_max_attempts:   # max retry attempts, if enabled
      retry_initial_backoff:   # Initial retry backoff, if enabled
      retry_max_backoff:   # Max retry backoff, if enabled
      retry_backoff_multiplier:   # Retry backoff multiplier, if enabled
      max_send_message_length:   # Max size of the send message
      max_received_message_length:   # Max size of the received message
      domain_mappings:
      - pattern: *.traceable.ai*
        proxy:
          host_name:   # Proxy hostname
          port:   # Proxy port
          user_name:   # Proxy user_name
          password:   # Proxy password
        tls:
          root_ca_file:   # Path to the root_ca file
          client_cert_file:   # Path to the client certificate PEM file
          client_key_file:   # Path to the decrypted client’s private-key PEM file
logging:
  logdir:   # Directory in which log files are stored <default: Traceable Home>
  logfile_mode: append/write   # <default: append>
  upload_bulk_count:   # Size of the batch in which logs are uploaded to the Traceable platform <default: 1000>
  should_upload_logs:   # Whether to upload logs to Traceable platform or not <default: True>
  level:   # Log level <default: INFO>
  api_log:   # Enable API level log <default: False>
  scan_extensive_log:   # Enable thread level log <default: False>
  max_log_size:   # Max log directory size <default: 10 GiB>
  max_scan_logs:   # Max number scan scoped logs to retain <default: 90>
  max_scan_log_duration:   # Max duration in days for which scan-scoped logs are retained <default: 30 days>
ast:
  hooks:
    hook_path:   # Path to the local hooks directory
  scan: 
    scan_name:   # Name of the scan wished to be run
    tags:   # Any additional tags for this scan run
    scan_timeout:   # Timeout in minutes after which the scan will abort, irrespective of the scan status
    traffic:
      env:   # Environment in which the scan is to be run
      target_url:   # URL at which active plugins will send requests
      graphql:
        schema_ids:   # IDs of the schema that is to be scanned
        scahema_files:   # Absolute file paths of the schema files that is to be scanned
        introspection_enabled:   # Enable GraphQL introspection
      oas:
        spec_ids:   # Ids of the spec that is to be scanned
        spec_files:   # Absolute file paths of the spec files that are to be scanned
      postman:
        postman_collection_id:   # ID of the collection that is to be scanned
        postman_environment_id:   # ID of environment where requests will be sent
        postman_collection:   # Absolute file path of the collection that is to be scanned
        postman_environment:   # Absolute file path of the environment where requests will be sent
      wsdl:
        spec_ids:   # Ids of the spec that is to be scanned
        spec_files:   # Absolute file paths of the spec files that are to be scanned
      live:
        local_traffic_capture:
          proxy:   # Start traffic capture proxy on given URL
          tpa_endpoint:   # Traceable Platform Agent endpoint URL
    assets:
      include_url_regex:
      exclude_url_regex:
      include_endpoint_labels:
      exclude_endpoint_labels:
      assign_endpoint_owner:   # generated_endpoint_owner 
      include_all_endpoint:
      include_endpoint_ids:
      include_service_ids:
      include_endpoint_with_owner_attributes:
      include_endpoint_owners:
      generated_endpoint_owner:
    attacks:
      policy:   # Policy to be used for finding vulnerabilities
      exclude_plugins:   # Comma-separated list of plugins to be excluded
    retest:
      test_ids:   # Comma separated list of test IDs that is to be retested
      scan_number:   # Scan run number that needs to be retested
      suite_id:   # Suite Id that needs to be retested
    heartbeat:
      interval:   # Frequency of runner heartbeat in seconds <default: 5 secs>
    advanced:
      transform_rules:   # transform rules
      parallelism:
        plugin_threads:   # Number of plugin runner threads to be spawned
        upload_threads:   # Number of result uploader threads to be spawned
        upload_bulk_count:   # Size of the batch in which test results are uploaded
      plugins:
        list:   # Comma-separated list of enabled plugins
        stats_enabled:   # Enable plugin-level stats
      experimental:
        test_results_upload_enabled:   # Use HTTP to upload test results <default: False>

Configuration sections

The following table defines the sections that are configurable in the YAML file above. This structure provides complete control over the CLI’s execution flow while maintaining consistency across environments and pipelines.

Logging

Traceable CLI 2.0 provides two logging modes that provide detailed observability into scan behavior. You can configure these modes through the logging section in the YAML file above.

Mode 1 — API logging

API Logging captures all requests and responses exchanged between the CLI and scanned APIs. This helps you identify request-level issues and validate scan interactions with your APIs. The following are some characteristics of this logging mode:

• It captures HTTP request and response data.

• It stores logs locally and does not upload them to the Traceable platform.

• It is available only when the log level is set to DEBUG.

Configuration Example

logging:
  api_log: True

Traceable stores the logs in the following file path:

<log_dir>/scans/<scan_id>_<scan_start_timestamp_sec>/api.log

Mode 2 — Extensive scan logging

Extensive Scan Logging provides detailed, thread- and process-level logs for scan execution. This helps trace the execution of plugins, runners, and threads, allowing for easier debugging and performance analysis. The following are some characteristics of this logging mode:

• It captures scan execution flow across threads and processes.

• It displays logs in the CLI and uploads them to the Traceable platform.

• You can configure this for any log level, but Traceable recommends using DEBUG for detailed insights.

Configuration Example

logging:
  scan_extensive_log: True

Traceable stores the logs in the following file path:

<log_dir>/scans/<scan_id>_<scan_start_timestamp_sec>/executor_<executor_id>.log

Log directory structure

Traceable organizes all logs under the scans directory inside the Traceable Home directory. Each scan creates a subdirectory named in the following format:

<scan_id>_<scan_start_timestamp>

Each scan directory contains the following log files:

• scan.log — This stores the general log for scan execution.

• api.log — The request or response log generated by API logging.

• executor_<id>.log — This stores the detailed execution log generated by Extensive Scan Logging.

By default, Traceable logs the latest 90 scans and retains them for 30 days.

Global Log Storage

Traceable also maintains a global log file (traceable.log) that aggregates activity across scan runs and maintains up to 10 files of 100 MiB each. The traceable.log file contains the combined logs of all runners and scans associated with the Traceable Home directory. When you start a scan, Traceable adds all the related logs to this file. Similarly, when a runner is active, both idle and active states are also logged.

Note

• Log entries generated by API logging (request and response logs recorded in api.log, if enabled) are not included in the traceable.log file.

• Runners or scans that reference a different Traceable Home directory are not recorded in the global log file; their logs are stored in the traceable.log file corresponding to the respective home directory.

Scan configuration

Traceable enables you to customize each scan to include environment details, timeout limits, and specific scan targets. The following is a code snippet for a sample scan configuration in the config.yaml file:

scan:
  scan_name: sample_scan
  tags: [api, regression]
  scan_timeout: 60
  traffic:
    env: production
    target_url: https://api.example.com

This configuration provides you with precise control over the scan scope and execution parameters.

Execution and performance configuration

The Traceable CLI also supports advanced configuration options for execution control, allowing you to manage concurrency, threading, and data upload behavior. The following is a code snippet for a sample scan configuration in the config.yaml file:

advanced:
  parallelism:
    plugin_threads: 20
    upload_threads: 5
  upload_bulk_count: 1000

These settings define how the Traceable CLI manages workload distribution and result uploads during scans, ensuring efficient performance and scalability.