cavil.conf

{
  # ---------------------------------------------------------------------------
  # Essential settings: review and change these for every new instance
  # ---------------------------------------------------------------------------

  # Secrets used to cryptographically sign session cookies
  secrets => ['this_is_not_secure'],

  # PostgreSQL server connection string
  pg => 'postgresql://sri@/legaldb-local',

  # Directory where source code to be scanned is stored, the space requirement can be significant since archives are
  # decompressed recursively and kept here for future reindexing
  checkout_dir => '/data/auto-co/legal-bot',

  # Temporary directory for incoming files, before they are moved to "checkout_dir"
  tmp_dir => '/data/auto-co/incoming',

  # Cache directory for temporary files shared between license pattern indexing processes
  cache_dir => '/data/auto-co/cache',

  # URL and token for the AI classifier, required for automated snippet resolution ("legacy" and "llama_cpp" are
  # supported); comment out to run with raw keyword matching only
  classifier => {
    type  => 'llama_cpp',
    url   => 'http://localhost:5000',
    token => 'API_TOKEN'
  },

  # ---------------------------------------------------------------------------
  # Authentication and source integration
  # ---------------------------------------------------------------------------

  # Optional OpenID Connect configuration for authentication
  openid => {
    key            => 'APP_NAME',
    secret         => 'APP_SECRET',
    well_known_url => 'https://id.opensuse.org/openidc/.well-known/openid-configuration'
  },

  # Authentication credentials for the Open Build Service (comment out to disable)
  obs => {
    'api.opensuse.org' => {
      user     => 'OBS_USER',
      password => 'OBS_PASSWORD'
    },
    'api.suse.de' => {
      user           => 'IBS_USER',
      ssh_key        => 'SSH_PRIVATE_KEY_PATH',
      embargoed_bugs => 'https://smash.suse.de/api/embargoed-bugs/'
    }
  },

  # Git configuration (comment out to disable)
  git => {
    bin            => '/usr/bin/git',
    extra_commands => [['/usr/lib/build/download_assets', '.']]
  },

  # Optional external link source rendering. These examples recognize common Open Build Service and source repository
  # request formats with neutral labels. Deployments can change the labels to match their workflow.
  external_link_sources => [
    {
      pattern => '^obs#(\\d+)$',
      url     => 'https://build.opensuse.org/request/show/$1',
      label   => 'external',
      title   => 'Build service request'
    },
    {
      pattern => '^ibs#(\\d+)$',
      url     => 'https://build.suse.de/request/show/$1',
      label   => 'internal',
      title   => 'Build service request'
    },
    {
      pattern => '^soo#([^!]+)!(\\d+)$',
      url     => 'https://src.opensuse.org/$1/pulls/$2',
      label   => 'external',
      title   => 'Gitea pull request'
    },
    {
      pattern => '^ssd#([^!]+)!(\\d+)$',
      url     => 'https://src.suse.de/$1/pulls/$2',
      label   => 'internal',
      title   => 'Gitea pull request'
    }
  ],

  # Token authentication strings for the dedicated bot REST API
  tokens => [],

  # ---------------------------------------------------------------------------
  # Engine, policy and tuning: sensible defaults, change as needed
  # ---------------------------------------------------------------------------

  # License pattern matching engine: "cavil" (Cavil::Matcher, the default) or "spooky"
  # (Spooky::Patterns::XS, the alternative, which must be installed separately). Both produce the same
  # token hashes, so switching is seamless and needs no migration; restart the web and job processes
  # after changing it.
  matcher => 'cavil',

  # Maximum acceptable risk for reports to be automatically considered "acceptable"
  acceptable_risk => 4,

  # Risk threshold for auto-accepting packages without prior manual review (set to 0 to disable)
  auto_accept_risk => 2,

  # Packages that are always considered "acceptable" (e.g. the openSUSE product build pseudo-packages)
  acceptable_packages => ['000product', '000release-packages', '000package-groups'],

  # Statistical resolution of high-similarity unresolved snippets, computed once at analyze time and
  # stored per occurrence (read by the report, file browser, SPDX, and triage filter); never mints
  # patterns. Changing a threshold takes effect on the next reindex or `cavil snippets --resolve`.
  #   - fold:  threshold + min_margin + max_risk -> assert the specific license (high confidence,
  #            unambiguous). risk 4 is clearly safe, 5 acceptable, 6+ never folds.
  #   - clear: clear_threshold (0 = off) -> clear recognized license boilerplate from the backlog
  #            WITHOUT asserting a license (no margin/risk gate). Most of the backlog is shared
  #            middle-of-license text whose real license is already found by title matching.
  #   - overlap: overlap_clear (0 = off) -> clear a snippet whose region already overlaps a real
  #            license match; overlap_guard keeps snippets that resemble a different license.
  #   - covered: cover_scope ('off'/'file'/'dir') -> clear a snippet when the file ('file') or its
  #            directory ('dir') already carries a concrete (non catch_all) license at least as risky.
  #            The covering match need not overlap the snippet; a higher-risk snippet is kept.
  #            cover_guard: in a LICENSE/COPYING-type file, when the snippet's OWN closest license is a
  #            grab-bag catch_all marker its risk read is unreliable, so it is only cleared when its
  #            similarity is at least this high (it genuinely is that boilerplate); a weaker, ambiguous
  #            match is kept for review (the "novel license bolted onto a retained standard one" case).
  #            Outside license files the same weak match is stray notice text and is still cleared.
  snippet_fold => {
    enabled         => 1,
    threshold       => 0.95,
    min_margin      => 0.15,
    max_risk        => 4,
    clear_threshold => 0.95,
    overlap_clear   => 1,
    overlap_guard   => 0.9,
    cover_scope     => 'dir',
    cover_guard     => 0.9
  },

  # Number of files per indexer process
  index_bucket_average => 600,

  # Number of packages per cleanup process
  cleanup_bucket_average => 400,

  # Number of days to keep reviewed packages when not part of a product before cleanup
  days_to_keep_orphaned_packages => 60,

  # Number of days to keep duplicate reviewed packages when not part of a product before cleanup
  days_to_keep_orphaned_duplicate_packages => 7,

  # Maximum number of files to show in reports per risk level
  min_files_short_report => 20,

  # Maximum length of email addresses to collect for reports
  max_email_url_size => 2048,

  # Memory limit for background jobs
  max_task_memory => 6_000_000_000,

  # Memory limit for application server worker processes
  max_worker_rss => 600000,

  # Maximum number of files with keyword matches to show in reports
  max_expanded_files => 20,

  # Maximum source file size to display in the file browser
  max_file_browser_size => 1_000_000,

  # Optional path to a file listing package files to skip during unpacking and indexing, one rule per line as
  # "package-name-glob : filename" (the glob is matched against the package name). Mainly used to defuse hostile
  # inputs such as zip bombs or archives that hang the unpacker. Comment out to disable.
  #exclude_file => '/etc/cavil/cavil.exclude',

  # How long finished Minion jobs are kept before removal, and after how long a running job is considered
  # "stuck", both in seconds (7 and 6 days here)
  minion_remove_after => 604800,
  minion_stuck_after  => 518400,

  # Always generate an SPDX report when a package has been indexed (instead of only on-demand)
  always_generate_spdx_reports => 0,

  # SPDX 3.0.1 SBOM generation (BSI TR-03183-2 compliant)
  spdx => {

    # Base URI for SBOM and element identifiers
    namespace => 'http://legaldb.suse.de/spdx/',

    # Entity that creates the SBOMs (BSI requires an email address, or a URL if none is available)
    creator => {
      name  => 'SUSE LLC',
      email => 'security@suse.de'
    },

    # Namespace for "LicenseRef-<entity>-*" identifiers minted for licenses unknown to SPDX and ScanCode
    license_ref_namespace => 'cavil'
  }
}