System Configuration

Configure the Safeguard CLI to match your organization's requirements and environment.

Configuration File

The CLI uses a YAML configuration file located at ~/.safeguard/config.yaml. Create or edit this file to customize CLI behavior.

Initialize Configuration

safeguard config init

This creates a default configuration file with common settings.

Configuration File Structure

# ~/.safeguard/config.yaml

# Authentication
api_key: ${SAFEGUARD_API_KEY}
organization: your-organization-id

# API Settings
api:
  base_url: https://api.safeguard.sh
  timeout: 300
  retry_count: 3

# Default Output Settings
output:
  format: cyclonedx-json
  directory: ./sbom
  pretty: true

# Scanning Settings
scan:
  include_dev: false
  depth: unlimited
  ignore_patterns:
    - "node_modules"
    - ".git"
    - "vendor"
    - "__pycache__"

# Policy Settings
policy:
  default: production
  fail_on: high
  allow_exceptions: true

# Proxy Settings
proxy:
  http: null
  https: null
  no_proxy: "localhost,127.0.0.1"

# Logging
logging:
  level: info
  file: ~/.safeguard/logs/cli.log

# Cache Settings
cache:
  enabled: true
  directory: ~/.safeguard/cache
  ttl: 86400  # 24 hours

Configuration Commands

View Configuration

# Show all configuration
safeguard config show

# Show specific value
safeguard config get api.base_url
safeguard config get output.format

Set Configuration

# Set individual values
safeguard config set output.format spdx-json
safeguard config set scan.include_dev true
safeguard config set policy.fail_on critical

# Set nested values
safeguard config set proxy.http http://proxy.example.com:8080

Reset Configuration

# Reset to defaults
safeguard config reset

# Reset specific section
safeguard config reset output

Environment Variables

Environment variables override configuration file settings:

Variable	Config Path	Description
`SAFEGUARD_API_KEY`	`api_key`	Authentication API key
`SAFEGUARD_ORG`	`organization`	Default organization ID
`SAFEGUARD_API_URL`	`api.base_url`	API endpoint URL
`SAFEGUARD_OUTPUT_DIR`	`output.directory`	Output directory
`SAFEGUARD_FORMAT`	`output.format`	Default output format
`SAFEGUARD_POLICY`	`policy.default`	Default policy name
`SAFEGUARD_DEBUG`	`logging.level`	Set to `debug` for verbose logging
`HTTP_PROXY`	`proxy.http`	HTTP proxy URL
`HTTPS_PROXY`	`proxy.https`	HTTPS proxy URL
`NO_PROXY`	`proxy.no_proxy`	Proxy bypass list

Project-Level Configuration

Create a .safeguard.yaml file in your project root to override global settings:

# .safeguard.yaml (in project root)

name: my-application
version: ${npm_package_version}

scan:
  include_dev: true
  ignore_patterns:
    - "test/**"
    - "docs/**"

policy: development

output:
  format: cyclonedx-json
  directory: ./security/sbom

Project configuration takes precedence over global configuration.

Toolset Configuration

Configure specific analysis tools and package managers:

# Toolset settings in config.yaml

toolset:
  # Node.js / npm
  npm:
    enabled: true
    include_dev: false
    registry: https://registry.npmjs.org
    
  # Python / pip
  pip:
    enabled: true
    index_url: https://pypi.org/simple
    
  # Java / Maven
  maven:
    enabled: true
    settings_file: ~/.m2/settings.xml
    
  # Go modules
  go:
    enabled: true
    proxy: https://proxy.golang.org
    
  # Rust / Cargo
  cargo:
    enabled: true
    
  # .NET / NuGet
  nuget:
    enabled: true
    sources:
      - https://api.nuget.org/v3/index.json

Ignore Patterns

Configure files and directories to exclude from scanning:

scan:
  ignore_patterns:
    # Version control
    - ".git"
    - ".svn"
    - ".hg"
    
    # Dependencies
    - "node_modules"
    - "vendor"
    - ".venv"
    - "__pycache__"
    
    # Build artifacts
    - "dist"
    - "build"
    - "target"
    - "out"
    
    # Test files
    - "**/*.test.js"
    - "**/*.spec.ts"
    - "test/**"
    - "tests/**"
    
    # Documentation
    - "docs/**"
    - "*.md"

You can also use a .safeguardignore file in your project root:

# .safeguardignore
node_modules/
vendor/
.git/
*.test.js
test/
docs/

Network Configuration

Proxy Settings

proxy:
  http: http://proxy.corporate.com:8080
  https: http://proxy.corporate.com:8080
  no_proxy: "localhost,127.0.0.1,.internal.com"

Custom CA Certificates

For environments with custom certificate authorities:

# Set CA bundle
safeguard config set api.ca_bundle /path/to/ca-bundle.crt

# Or use environment variable
export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt

Offline Mode

For air-gapped environments:

offline:
  enabled: true
  database_path: /path/to/vulnerability-db
  skip_upload: true

Credential Management

Secure Credential Storage

The CLI can store credentials securely using your system's keychain:

# Enable keychain storage
safeguard config set credentials.use_keychain true

# Store API key in keychain
safeguard auth set-key --secure YOUR_API_KEY

Registry Credentials

Configure container registry credentials:

registries:
  docker.io:
    username: ${DOCKER_USERNAME}
    password: ${DOCKER_PASSWORD}
    
  myregistry.azurecr.io:
    username: ${AZURE_CLIENT_ID}
    password: ${AZURE_CLIENT_SECRET}
    
  gcr.io:
    key_file: /path/to/service-account.json

Logging Configuration

logging:
  level: info  # debug, info, warn, error
  file: ~/.safeguard/logs/cli.log
  max_size: 10MB
  max_files: 5
  format: json  # json, text

Enable debug logging:

# Via environment variable
export SAFEGUARD_DEBUG=true

# Via config
safeguard config set logging.level debug

Performance Tuning

performance:
  # Parallel processing
  workers: 4
  
  # Memory limits
  max_memory: 4096  # MB
  
  # Timeouts
  scan_timeout: 600  # seconds
  upload_timeout: 300

System Configuration

System Configuration

Configuration File

Initialize Configuration

Configuration File Structure

Configuration Commands

View Configuration

Set Configuration

Reset Configuration

Environment Variables

Project-Level Configuration

Toolset Configuration

Ignore Patterns

Network Configuration

Proxy Settings

Custom CA Certificates

Offline Mode

Credential Management

Secure Credential Storage

Registry Credentials

Logging Configuration

Performance Tuning

Next Steps

On this page