Monitoring detect-secrets with Vigilmon

detect-secrets (by Yelp) is an open source tool for detecting and preventing hardcoded secrets in source code. Unlike forensic scanners that search git history after the fact, detect-secrets is designed for prevention — it runs as a git pre-commit hook that blocks commits containing new secrets, and maintains a .secrets.baseline file that records known false positives to avoid alert fatigue. For organizations managing many repositories, detect-secrets can be deployed as a centralized server (Python FastAPI, port 5000) that aggregates baseline files, audit results, and secret detection reports across teams. If this server goes down or the pre-commit hooks drift out of sync, secrets can slip into commits without any detection layer in place. Vigilmon keeps the detect-secrets infrastructure continuously monitored so your prevention layer never goes dark silently.

What You'll Set Up

• HTTP uptime monitor for the detect-secrets API server (port 5000)
• Database connectivity monitor for scan results and audit history
• Cron heartbeat for baseline freshness monitoring
• Cron heartbeat for CI/CD integration health
• SSL certificate expiry alerts for the API server
• Alert channels with appropriate thresholds

Prerequisites

• detect-secrets server deployed (Python FastAPI on port 5000) — or detect-secrets CLI integrated into CI/CD
• Database backend accessible (PostgreSQL, MySQL, or SQLite)
• Pre-commit hooks installed on developer machines (verify with pre-commit --version)
• A free Vigilmon account

Step 1: Monitor the detect-secrets API Server (Port 5000)

The centralized detect-secrets API server is where teams push baseline updates, audit results, and secret detection reports. It gives security teams a single dashboard for managing .secrets.baseline files across many repositories. If the server goes down, CI/CD pipelines cannot report new findings to the central store, and the audit backlog management workflow breaks.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. URL: https://detect-secrets.yourdomain.com/health (or http://your-server-ip:5000/health).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Enable Monitor SSL certificate and set Alert when certificate expires in less than 21 days.
7. Click Save.

FastAPI exposes automatic documentation at /docs — if no explicit health endpoint exists, use the docs route:

1. URL: http://your-server-ip:5000/docs
2. Expected HTTP status: 200
3. Under Keyword check, enter Swagger to verify the FastAPI docs page loaded correctly.

Step 2: Monitor Database Connectivity

The detect-secrets server stores scan results, baseline history, team audit logs, and plugin configuration in a database. If the database becomes unavailable, the server typically returns errors on all write operations — new scan reports are lost, and audit history is inaccessible.

For PostgreSQL:

1. Click Add Monitor → TCP Port.
2. Host: localhost (or your PostgreSQL host).
3. Port: 5432
4. Check interval: 1 minute
5. Click Save.

For MySQL/MariaDB:

1. Click Add Monitor → TCP Port.
2. Host: localhost (or your MySQL host).
3. Port: 3306
4. Check interval: 1 minute
5. Click Save.

Pair this TCP check with the API server monitor in Step 1. If the API server returns 500 errors while the database TCP port is open, the database connection pool may be exhausted without the port going down.

Step 3: Heartbeat Monitor for Baseline Freshness

The .secrets.baseline file is the core artifact that detect-secrets uses to track known false positives and audit state. As the codebase changes, the baseline must be regenerated periodically to stay accurate — a stale baseline accumulates noise (new legitimate high-entropy strings flagged as secrets) and risks hiding genuinely new secrets that were added after the last audit.

Set up a heartbeat that fires when the baseline update process runs successfully:

1. Click Add Monitor → Cron Heartbeat.
2. Set the expected interval to 168 hours (7 days) — alert if a repository's baseline has not been re-audited within a week.
3. Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/abc123).
4. Add the heartbeat ping to your baseline update script:

#!/bin/bash
# /opt/detect-secrets/refresh-baseline.sh
REPO_PATH=${1:-$(pwd)}

cd "$REPO_PATH" || exit 1

# Regenerate the baseline
detect-secrets scan > .secrets.baseline.new

if [ "$?" -eq "0" ]; then
  mv .secrets.baseline.new .secrets.baseline
  git add .secrets.baseline
  git commit -m "chore: refresh secrets baseline [skip ci]" || true

  # Signal successful baseline refresh to Vigilmon
  curl -s https://vigilmon.online/heartbeat/abc123
fi

For repositories managed centrally, run this script weekly per repository and aggregate the results. If any repository's heartbeat stops arriving within the 7-day window, Vigilmon alerts the security team that the baseline is going stale.

Step 4: Heartbeat Monitor for CI/CD Integration Health

detect-secrets can run in CI to catch secrets that bypassed the pre-commit hook (developers may skip hooks with --no-verify, or machines without hooks installed). A CI step that silently fails or is accidentally removed leaves this backstop layer broken.

1. Click Add Monitor → Cron Heartbeat.
2. Set the expected interval to match your CI cadence — for teams that push multiple times daily, use 4 hours; for less active repositories, use 24 hours.
3. Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/def456).
4. Add the heartbeat ping to your CI pipeline's detect-secrets step:

GitHub Actions:

- name: Run detect-secrets
  run: |
    pip install detect-secrets
    detect-secrets scan --baseline .secrets.baseline
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq "0" ]; then
      curl -s https://vigilmon.online/heartbeat/def456
    fi
    exit $EXIT_CODE

GitLab CI:

detect-secrets:
  stage: security
  script:
    - pip install detect-secrets
    - detect-secrets scan --baseline .secrets.baseline
    - curl -s https://vigilmon.online/heartbeat/def456
  allow_failure: false

If the CI pipeline runs but the detect-secrets step is skipped, removed, or errors out before the heartbeat ping, Vigilmon alerts after the expected interval — catching pipeline drift before it becomes a coverage gap.

Step 5: Monitor Pre-commit Hook Version Consistency

Pre-commit hook drift — different developers running different versions of detect-secrets — can cause inconsistent baseline formats and scanning behavior. While Vigilmon cannot directly monitor individual developer machines, you can track hook health through your CI pipeline's weekly audit report.

Create a CI job that audits hook versions across the organization and pings a separate heartbeat:

#!/bin/bash
# Audit hook consistency (run in CI weekly)

EXPECTED_VERSION=$(detect-secrets --version 2>&1 | grep -oP '[\d.]+')
echo "Scanning with detect-secrets version: $EXPECTED_VERSION"

# Report version to central server
curl -s -X POST https://detect-secrets.yourdomain.com/api/version-report \
  -H "Content-Type: application/json" \
  -d "{\"repo\": \"$CI_PROJECT_NAME\", \"version\": \"$EXPECTED_VERSION\"}"

# Ping heartbeat confirming audit completed
curl -s https://vigilmon.online/heartbeat/ghi789

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. For the detect-secrets API server monitor, set Consecutive failures before alert to 2 — FastAPI restarts during deployments cause brief probe failures.
3. For the database TCP monitor, set Consecutive failures to 1 — database loss immediately breaks scan result persistence.
4. For the baseline freshness heartbeat (7-day window), Vigilmon alerts automatically after the interval passes without a ping.
5. For the CI/CD integration heartbeat, match alert sensitivity to your deployment risk — active repositories pushing frequently should alert after 6 hours of no CI heartbeat; quieter repositories can tolerate longer windows.
6. For the SSL certificate monitor, set alerts to 21 days before expiry.

Docker Compose Health Check Integration

If you deployed the detect-secrets server via Docker Compose, add health checks aligned with your Vigilmon monitors:

services:
  detect-secrets-api:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  postgres:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U detect_secrets"]
      interval: 30s
      timeout: 10s
      retries: 5

Docker's internal health checks drive container restarts. Vigilmon provides the external view — confirming the server is reachable from CI/CD pipelines and that the detection pipeline is actually running.

Summary

| Monitor | Target | What It Catches | |---|---|---| | API server | :5000/health | Central server crash, reports not accepted | | Database TCP | :5432 / :3306 | Scan result persistence broken | | Baseline freshness heartbeat | Heartbeat URL (weekly) | Baseline stale >7 days without re-audit | | CI/CD integration heartbeat | Heartbeat URL (4–24h) | CI scan step removed or silently failing | | Pre-commit audit heartbeat | Heartbeat URL (weekly) | Version drift audit not running | | SSL certificate | API server domain | TLS expiry on central server |

detect-secrets is your first line of defense against hardcoded credentials reaching your codebase — but only if the pre-commit hooks are installed, the CI backstop is running, and the baseline files are fresh. With Vigilmon watching the API server, database, baseline freshness, and CI/CD integration health, you get alerted when any part of your secret prevention layer goes dark before developers unknowingly commit credentials that bypass detection.