Identity Watchlist User Guide

Audience: Security operators, compliance owners, and CI/release engineers who manage signing trust in Stella Ops.

Purpose: Configure and operate the Attestor identity watchlist to detect when specific signing identities appear in Rekor transparency log entries, and to route alerts when they do.

Overview

The identity watchlist enables proactive alerting when specific signing identities appear in Rekor transparency log entries. Common use cases:

• Threat Detection: Monitor for known malicious or compromised signing identities
• Compliance Monitoring: Track when specific OIDC issuers sign artifacts
• Operational Awareness: Get notified when CI/CD workflows from specific repositories sign releases
• Key Tracking: Monitor usage of specific signing keys across your organization

Core Concepts

Watchlist Entries

A watchlist entry defines an identity pattern to monitor and alert configuration:

You must supply at least one of issuer, subjectAlternativeName, or keyId so the entry has an identity dimension to match against.

Match Modes

Note: Regex mode has a 100ms timeout and pattern validation. Use sparingly for performance-critical environments.

Severity Levels

Scope Levels

Console and frontdoor watchlist flows use the canonical trust scope family: trust:read, trust:write, and trust:admin. Legacy watchlist:* aliases remain accepted for older clients, but new integrations should use the trust scopes.

CLI Usage

Adding a Watchlist Entry

Monitor a specific OIDC issuer:

stella watchlist add \
  --issuer "https://token.actions.githubusercontent.com" \
  --name "GitHub Actions" \
  --severity warning \
  --description "Track all GitHub Actions signatures"

Monitor email patterns with glob matching:

stella watchlist add \
  --san "*@malicious-domain.com" \
  --match-mode glob \
  --severity critical \
  --name "Malicious Domain"

Listing Entries

List all entries including global ones:

stella watchlist list --include-global

Output as JSON for scripting:

stella watchlist list --format json

Testing Patterns

Test if an identity would trigger an alert:

stella watchlist test <entry-id> \
  --issuer "https://token.actions.githubusercontent.com" \
  --san "repo:org/repo:ref:refs/heads/main"

Managing Entries

Update an entry:

stella watchlist update <entry-id> --enabled false
stella watchlist update <entry-id> --severity critical

Delete an entry:

stella watchlist remove <entry-id>
stella watchlist remove <entry-id> --force  # Skip confirmation

Viewing Alerts

List recent alerts:

stella watchlist alerts --since 24h
stella watchlist alerts --severity critical --limit 50

API Usage

Create Entry

POST /api/v1/watchlist
Content-Type: application/json

{
  "displayName": "GitHub Actions Monitor",
  "issuer": "https://token.actions.githubusercontent.com",
  "matchMode": "prefix",
  "severity": "warning",
  "description": "Monitor all GitHub Actions signatures",
  "enabled": true,
  "suppressDuplicatesMinutes": 60
}

List Entries

GET /api/v1/watchlist?includeGlobal=true

Test Pattern

POST /api/v1/watchlist/{id}/test
Content-Type: application/json

{
  "issuer": "https://token.actions.githubusercontent.com",
  "subjectAlternativeName": "repo:org/repo:ref:refs/heads/main"
}

Alert Deduplication

To prevent alert storms, the watchlist system deduplicates alerts based on:

1. Watchlist Entry ID - Which entry triggered the alert
2. Identity Hash - SHA-256 of the matched identity fields

Configure the deduplication window per entry with suppressDuplicatesMinutes (default: 60 minutes).

When an alert is suppressed, subsequent alerts will include a suppressedCount indicating how many similar alerts were skipped.

Best Practices

Pattern Design

1. Start specific, broaden as needed: Begin with exact matches before using wildcards
2. Test before deploying: Use the test endpoint to validate patterns
3. Document why: Always include a description explaining the monitoring purpose
4. Use appropriate match modes:
   • exact for known bad actors
   • prefix for issuer families (e.g., all Google issuers)
   • glob for email/SAN patterns
   • regex only when simpler modes can’t express the pattern

Performance Considerations

• Limit regex patterns to < 256 characters
• Avoid catastrophic backtracking patterns (e.g., (a+)+)
• Monitor the attestor.watchlist.scan_latency_seconds metric
• Keep watchlist size reasonable (< 1000 entries per tenant)

Alert Management

1. Set appropriate severity: Reserve critical for genuine emergencies
2. Configure dedup windows: Use shorter windows (5-15 min) for critical entries
3. Review suppressed counts: High counts may indicate a pattern is too broad
4. Route appropriately: Use channel overrides for sensitive entries

Monitoring & Metrics

The following OpenTelemetry metrics are exposed:

Troubleshooting

Entry Not Matching Expected Identity

1. Verify the match mode is appropriate for your pattern
2. Use the test endpoint with verbose output
3. Check if the entry is enabled
4. Remember that all match modes are case-insensitive — a pattern that relies on case will not behave as expected

Too Many Alerts

1. Increase suppressDuplicatesMinutes
2. Narrow the pattern (more specific issuer, SAN prefix)
3. Consider if the pattern is too broad

Missing Alerts

1. Verify the entry is enabled
2. Check if alerts are being suppressed (view suppressed count)
3. Verify notification routing is configured
4. Check service logs for matching errors

Related Documentation

• Attestor Architecture
• Notification Templates
• Watchlist Monitoring Runbook
• Offline Verification Guide