Documentation

1. Purpose

The CBOM Discover_SourceCode sensor scans local filesystem Git repositories and source archives for hardcoded cryptographic material embedded directly in source code. This includes private keys, public certificates, PEM blocks, API tokens, symmetric encryption keys, and other secrets that developers may have inadvertently committed to version control or packaged into release archives.

This guide covers:

Identifying local Git repository root paths and source archive locations accessible to the sensor
Ensuring the sensor service account has the necessary read-only filesystem permissions
Configuring recursive scanning across repository subdirectories and branches
Setting up full-history scanning using mirrored clones for complete coverage
Providing the correct YAML configuration for the Discover_SourceCode sensor
Validating that the sensor is discovering cryptographic assets as expected

The sensor operates entirely at the filesystem level and does not require any network credentials, API tokens, or remote authentication. All access is read-only.

2. Prerequisites

Before configuring the Discover_SourceCode sensor, ensure the following are in place:

The CBOM sensor agent is installed and running on the host that has direct filesystem access to the target repositories or archives.
The service account under which the CBOM sensor runs (referred to as cbom-sensor throughout this guide) exists on the host system.
Git is installed on the scanning host if branch-level or history scanning is required:
```
git --version
```
The target Git repositories are cloned or mirrored locally and are accessible from the scanning host filesystem.
Source archives (.zip, .tar.gz) to be scanned are stored in a known local directory.
Sufficient disk space is available if performing --mirror clones for full-history scanning (mirror clones replicate all refs and objects).
The scanning host has Python 3.8+ or the CBOM agent runtime installed, as required by the sensor framework.

3. Verify and Grant Filesystem Read Access

The Discover_SourceCode sensor requires read access to all paths listed in the configuration. No write or execute permissions are needed beyond directory traversal.

3.1 Identify the Sensor Service Account

Confirm the user account under which the CBOM agent process runs:

ps aux | grep cbom

The output will show the owning user. In this guide, the service account is assumed to be cbom-sensor. Adjust commands as needed for your environment.

3.2 Check Current Permissions on Repository Paths

Verify that the service account can read the target directories:

ls -la /opt/repositories/
ls -la /var/source-archives/

Check effective access for the sensor service account:

sudo -u cbom-sensor ls /opt/repositories/my-app

If the command returns a permission denied error, proceed to the next step.

3.3 Grant Read Access to the Service Account

Grant read and execute permissions to the sensor service account on the repository root. Execute permissions on directories are required for directory traversal.

For a single repository:

sudo setfacl -R -m u:cbom-sensor:rX /opt/repositories/my-app

For an entire repository root directory:

sudo setfacl -R -m u:cbom-sensor:rX /opt/repositories/

For a source archives directory:

sudo setfacl -R -m u:cbom-sensor:rX /var/source-archives/

If ACLs are not available on the filesystem, use group-based permissions instead:

sudo usermod -aG reporead cbom-sensor
sudo chgrp -R reporead /opt/repositories/
sudo chmod -R g+rX /opt/repositories/

3.4 Confirm Access After Permission Grant

Re-verify that the service account can now list and read files:

sudo -u cbom-sensor ls -la /opt/repositories/my-app
sudo -u cbom-sensor cat /opt/repositories/my-app/config/keys.conf

Both commands should succeed without errors before proceeding.

4. Prepare Local Git Repositories for Scanning

4.1 Standard Repository Clone

For current HEAD branch scanning, a standard clone is sufficient:

git clone https://github.com/your-org/your-repo.git /opt/repositories/your-repo

Ensure the clone is up to date before each sensor run:

git -C /opt/repositories/your-repo pull

4.2 Mirror Clone for Full History Scanning

To scan all branches, tags, and the complete commit history for cryptographic material that may have been introduced and later deleted, use a mirror clone. This is the recommended approach for thorough security assessments.

git clone --mirror https://github.com/your-org/your-repo.git /opt/repositories/your-repo.git

Update a mirror clone before scanning:

git -C /opt/repositories/your-repo.git remote update

Mirror clones are bare repositories (no working tree). The Discover_SourceCode sensor supports bare repositories and will scan all packed refs and object store contents when include_bare_repos: true is set in the configuration.

4.3 Organize Multiple Repositories

If scanning many repositories, organize them under a single root directory to simplify configuration:

/opt/repositories/
  your-repo/
  another-service/
  legacy-app.git        # mirror clone
  third-party-lib/

Set the local_paths configuration entry to the root directory to enable recursive discovery of all repositories beneath it.

5. Prepare Source Archives for Scanning

The Discover_SourceCode sensor supports scanning compressed source archives without requiring manual extraction. Supported formats include .zip, .tar.gz, and .tar.bz2.

5.1 Locate or Collect Archives

Place all archives to be scanned in a dedicated directory:

sudo mkdir -p /var/source-archives
sudo chown cbom-sensor:cbom-sensor /var/source-archives

Copy or move archives into this location:

cp /home/builds/release-v2.4.1.tar.gz /var/source-archives/
cp /home/builds/legacy-export-2023.zip /var/source-archives/

5.2 Verify Archive Integrity

Confirm archives are readable and not corrupted before scanning:

# For tar.gz archives
tar -tzf /var/source-archives/release-v2.4.1.tar.gz | head -20

# For zip archives
unzip -l /var/source-archives/legacy-export-2023.zip | head -20

6. Configure CBOM Sensor

Add or update the Discover_SourceCode sensor configuration in your CBOM sensor configuration file. The configuration specifies the local paths to scan, scanning behavior, and output settings.

sensors:
  - name: Discover_SourceCode
    enabled: true
    sensor_type: source_code
    schedule: "0 2 * * *"          # Run daily at 02:00 local time

    source:
      local_paths:
        - /opt/repositories/        # Root directory; all subdirectories scanned recursively
        - /var/source-archives/     # Directory containing .zip and .tar.gz archives

      recursive: true               # Recurse into subdirectories under each local_path
      follow_symlinks: false        # Do not follow symbolic links (prevents loops)
      include_bare_repos: true      # Scan bare/mirror clones (*.git directories)

      # Branch selection for non-bare Git repositories
      # "all" scans every local branch; specify branch names to limit scope
      git_branches:
        - all                       # Alternatively: ["main", "develop", "release/*"]

      # Archive handling
      scan_archives: true
      archive_extensions:
        - .zip
        - .tar.gz
        - .tar.bz2

      # File inclusion and exclusion patterns
      include_patterns:
        - "**/*.pem"
        - "**/*.crt"
        - "**/*.cer"
        - "**/*.key"
        - "**/*.p12"
        - "**/*.pfx"
        - "**/*.jks"
        - "**/*.conf"
        - "**/*.yaml"
        - "**/*.yml"
        - "**/*.env"
        - "**/*.json"
        - "**/*.xml"
        - "**/*.properties"
        - "**/*.py"
        - "**/*.java"
        - "**/*.go"
        - "**/*.js"
        - "**/*.ts"

      exclude_patterns:
        - "**/node_modules/**"
        - "**/.git/objects/**"      # Raw git object store handled separately by bare-repo scan
        - "**/vendor/**"
        - "**/dist/**"
        - "**/__pycache__/**"

      # Maximum file size to scan (bytes); larger files are skipped with a warning
      max_file_size_bytes: 10485760   # 10 MB

    output:
      findings_format: json
      output_path: /var/cbom/output/source_code_findings.json
      log_level: info

    service_account: cbom-sensor

Save the configuration file and restart the CBOM agent to apply changes:

sudo systemctl restart cbom-agent

7. Validation

After restarting the agent, confirm the sensor is operating correctly.

7.1 Check Agent Status

sudo systemctl status cbom-agent

The output should show active (running) with no error lines.

7.2 Review Sensor Logs

Tail the CBOM agent log to observe the Discover_SourceCode sensor activity:

sudo journalctl -u cbom-agent -f | grep Discover_SourceCode

Expected log output during a successful scan:

INFO  Discover_SourceCode  Starting scan of local_paths: ['/opt/repositories/', '/var/source-archives/']
INFO  Discover_SourceCode  Discovered 4 Git repositories under /opt/repositories/
INFO  Discover_SourceCode  Scanning branch 'main' in /opt/repositories/your-repo
INFO  Discover_SourceCode  Scanning archive: /var/source-archives/release-v2.4.1.tar.gz
INFO  Discover_SourceCode  Scan complete. 23 cryptographic assets discovered. Output written to /var/cbom/output/source_code_findings.json

7.3 Inspect the Findings Output

cat /var/cbom/output/source_code_findings.json | python3 -m json.tool | head -60

Confirm the output contains entries with asset_type values such as RSA_PRIVATE_KEY, X509_CERTIFICATE, or API_TOKEN, along with the file path and line number where each asset was found.

7.4 Manual On-Demand Scan

Trigger a manual scan to validate configuration without waiting for the cron schedule:

cbom-agent run-sensor --name Discover_SourceCode --once

8. Common Errors and Resolution

Error 1: Permission denied when accessing repository path

ERROR Discover_SourceCode  Failed to open /opt/repositories/my-app: Permission denied

Cause: The cbom-sensor service account does not have read access to the specified path.

Fix: Grant read access using ACLs or group permissions as described in Section 3. Verify effective permissions with sudo -u cbom-sensor ls /opt/repositories/my-app before restarting the agent.

Error 2: Archive extraction failure — corrupt or incomplete file

ERROR Discover_SourceCode  Failed to extract archive /var/source-archives/export.tar.gz: EOFError: Compressed file ended before the end-of-stream marker was reached

Cause: The archive file is incomplete, corrupted, or was still being written when the sensor attempted to open it.

Fix: Verify archive integrity using tar -tzf /var/source-archives/export.tar.gz. Replace the file with a complete copy. If archives are generated by a build pipeline, ensure the sensor schedule runs after the build process completes and files are fully flushed to disk.

Error 3: Git repository detected but no branches scanned

WARN  Discover_SourceCode  No branches found in /opt/repositories/legacy-app — skipping Git scan

Cause: The directory is a bare mirror clone where local branches may not be checked out in the expected ref format, or the repository has no commits on any branch.

Fix: For mirror clones, ensure include_bare_repos: true is set in the sensor configuration. Verify that the mirror clone is healthy:

git -C /opt/repositories/legacy-app.git branch -a

If the repository is truly empty, it can be excluded via the exclude_patterns list.

9. Security Recommendations

Run the cbom-sensor service account with the principle of least privilege: grant read-only access strictly to the repository and archive directories defined in local_paths, and no other filesystem locations.
Do not run the CBOM agent as root. Use a dedicated low-privilege service account and ACLs to scope access precisely to only the paths that need scanning.
Store mirror clones on a dedicated scanning volume separate from production repository storage to prevent any accidental modification of source repositories during the scanning process.
Rotate and review the list of local_paths regularly, especially after onboarding new projects or decommissioning old ones, to ensure the sensor scope remains accurate and does not accumulate stale or irrelevant paths.
Restrict access to the findings output file so that only authorized security personnel and the CBOM platform can read it. Findings may contain partial key material or sensitive path information:
```
sudo chmod 640 /var/cbom/output/source_code_findings.json
sudo chown cbom-sensor:security-team /var/cbom/output/source_code_findings.json
```

10. Conclusion

The Discover_SourceCode sensor provides comprehensive, read-only scanning of local Git repositories and source archives for hardcoded cryptographic material without requiring any network credentials or remote API access. By configuring appropriate filesystem permissions, using mirror clones for full-history coverage, and organizing paths under a structured root directory, security teams can ensure that all cryptographic assets embedded in source code are continuously discovered and inventoried. Regular scheduled scans combined with the findings output feed the broader CBOM platform, enabling teams to track, remediate, and govern cryptographic usage across their entire codebase.

CBOM Secure

Local Git Repositories and Source Archives Setup Guide for CBOM Source Code Repository Sensor