git.stella-ops.org/docs/training/unknowns-management-guide.md

Unknowns Management Guide

Sprint: SPRINT_3500_0004_0004
Audience: Security Engineers, SOC Analysts, DevOps

Introduction

The Unknowns Registry tracks components that cannot be fully analyzed due to missing data, unrecognized formats, or resolution failures. This guide explains how to manage unknowns effectively to maintain scan coverage and reduce blind spots.

---

What are Unknowns?

During vulnerability scanning, some components cannot be analyzed:

Scan Results:
✅ 245 components analyzed
⚠️  12 unknowns registered

Unknowns:
- pkg:npm/internal-lib@1.0.0    → unmapped_purl (no CVE mapping)
- pkg:pypi/custom-tool@2.3.1    → checksum_miss (not in advisory DB)
- [native binary]               → language_gap (unsupported)

Why Unknowns Matter:

• They represent blind spots in your security posture
• Untracked unknowns accumulate over time
• Some may hide critical vulnerabilities

---

Categories of Unknowns

Category	Description	Common Causes
unmapped_purl	No CVE/advisory mapping exists	Internal packages, new releases
checksum_miss	Binary checksum not found	Modified binaries, custom builds
language_gap	Language not supported	COBOL, Fortran, proprietary
parsing_failure	Manifest couldn't be parsed	Corrupted files, unusual formats
network_timeout	Advisory feed unavailable	Network issues, rate limiting
unrecognized_format	Unknown file format	Custom packaging, obfuscation

---

The 2-Factor Ranking System

Unknowns are prioritized using two factors:

Factor 1: Vulnerability Potential (0-5)

How likely is this component to have vulnerabilities?

Score	Criteria
5	External dependency with network exposure
4	External dependency, no network exposure
3	Internal dependency with external data handling
2	Internal dependency, limited exposure
1	Development-only tooling
0	Static assets, documentation

Factor 2: Impact Potential (0-5)

If vulnerable, how severe would exploitation be?

Score	Criteria
5	Handles authentication, encryption, or PII
4	Business-critical functionality
3	User-facing features
2	Internal tooling
1	Logging, monitoring
0	No runtime impact

Combined Priority

Priority = Vulnerability × Impact

Priority Score	Level	Action
20-25	Critical	Investigate immediately
12-19	High	Review within 24 hours
6-11	Medium	Review within 1 week
1-5	Low	Track and monitor

---

Core Workflows

1. Daily Triage

Review and categorize new unknowns:

# Step 1: Get summary
stella unknowns summary --workspace-id $WS_ID

# Step 2: List high-priority pending
stella unknowns list --status pending --min-score 12

# Step 3: Review each
stella unknowns show --id unknown-001

# Step 4: Take action (escalate, resolve, or suppress)
stella unknowns escalate --id unknown-001 --reason "Needs security review"

2. Escalation

When an unknown requires expert review:

stella unknowns escalate \
  --id unknown-001 \
  --reason "Custom cryptographic library - needs audit" \
  --assignee security-team \
  --severity high \
  --due-date 2025-12-27

When to escalate:

• Priority score ≥ 12
• Cryptographic or security-related components
• Components handling sensitive data
• Public-facing dependencies

3. Resolution

Mark unknowns as resolved with documentation:

# Resolved: Mapping added
stella unknowns resolve --id unknown-001 \
  --resolution mapped \
  --comment "Added CPE mapping to internal DB"

# Resolved: Not applicable
stella unknowns resolve --id unknown-002 \
  --resolution not_applicable \
  --comment "Development-only tool, not in production"

# Resolved: Component removed
stella unknowns resolve --id unknown-003 \
  --resolution removed \
  --comment "Replaced with supported alternative"

4. Suppression

Accept risk for known-safe unknowns:

stella unknowns suppress \
  --id unknown-004 \
  --reason "Internal UI component, no external exposure" \
  --expires 2026-01-01 \
  --scope workspace \
  --approver security@example.com

Suppression best practices:

• Always set an expiration date
• Document the risk assessment
• Require approver for production suppressions
• Review suppressions quarterly

5. Bulk Triage

Process multiple unknowns efficiently:

# Create triage file
cat > triage.json << 'EOF'
{
  "decisions": [
    {
      "id": "unknown-001",
      "action": "resolve",
      "resolution": "mapped",
      "comment": "Added mapping"
    },
    {
      "id": "unknown-002",
      "action": "suppress",
      "reason": "Dev-only tool",
      "expires": "2026-01-01"
    }
  ]
}
EOF

# Preview
stella unknowns bulk-triage --file triage.json --dry-run

# Apply
stella unknowns bulk-triage --file triage.json

---

Understanding Unknown Details

Example Unknown Record

stella unknowns show --id unknown-001 --verbose

Output:

id: unknown-001
purl: pkg:npm/custom-auth@3.2.1
category: unmapped_purl
status: pending

scoring:
  vulnerabilityPotential: 5  # External auth library
  impactPotential: 5         # Handles authentication
  priorityScore: 25          # CRITICAL

metadata:
  firstSeen: 2025-12-15T08:00:00Z
  lastSeen: 2025-12-20T10:00:00Z
  affectedScans: 15
  affectedImages: 3

context:
  files:
    - node_modules/custom-auth/package.json
    - package-lock.json
  dependencyPath:
    - app → express → custom-auth

analysis:
  reason: "No CVE/advisory mapping exists for this package"
  attempts:
    - source: nvd
      result: no_match
    - source: ghsa
      result: no_match
    - source: osv
      result: no_match
  suggestions:
    - "Search for upstream security advisories"
    - "Contact vendor for security information"
    - "Consider static analysis of source code"

---

Status Lifecycle

┌─────────────┐
│   pending   │ ◄──── New unknown detected
└──────┬──────┘
       │
       ├───────────────┬───────────────┐
       │               │               │
       ▼               ▼               ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│  escalated  │ │ suppressed  │ │  resolved   │
└──────┬──────┘ └──────┬──────┘ └─────────────┘
       │               │
       ▼               ▼
┌─────────────┐ ┌─────────────┐
│  resolved   │ │  (expires)  │────▶ pending
└─────────────┘ └─────────────┘

---

Integration Patterns

CI/CD Pipeline

# .github/workflows/security.yml
- name: Scan for vulnerabilities
  run: stella scan run --image $IMAGE

- name: Check unknowns threshold
  run: |
    CRITICAL_UNKNOWNS=$(stella unknowns list \
      --scan-id $SCAN_ID \
      --min-score 20 \
      --output-format json | jq 'length')
    
    if [ "$CRITICAL_UNKNOWNS" -gt 0 ]; then
      echo "::error::$CRITICAL_UNKNOWNS critical unknowns detected"
      exit 1
    fi

- name: Archive unknowns report
  run: |
    stella unknowns export \
      --scan-id $SCAN_ID \
      --output unknowns-${{ github.sha }}.json

Metrics and Monitoring

Track unknowns over time:

# Export metrics for Prometheus/Grafana
stella unknowns summary --workspace-id $WS_ID --output-format json > /metrics/unknowns.json

Key metrics to track:

• Total unknowns count (by status)
• Average time to resolution
• Suppression rate
• Unknown-to-finding ratio

SIEM Integration

Forward unknowns to your SIEM:

# Export in SIEM-compatible format
stella unknowns export \
  --workspace-id $WS_ID \
  --status pending,escalated \
  --format ndjson \
  --output /var/log/stella/unknowns.ndjson

---

Best Practices

1. Don't Ignore Unknowns

Every unknown is a potential blind spot:

# Weekly review of all unknowns
stella unknowns list --status pending --sort firstSeen --order asc

2. Set SLAs by Priority

Priority	Target Resolution
Critical (20-25)	24 hours
High (12-19)	3 days
Medium (6-11)	1 week
Low (1-5)	2 weeks

3. Document Everything

Resolution comments help future triage:

# Good
stella unknowns resolve --id unknown-001 \
  --resolution mapped \
  --comment "Added CPE cpe:2.3:a:vendor:product:1.0.0. Mapping verified against vendor advisory VA-2025-001."

# Bad
stella unknowns resolve --id unknown-001 \
  --resolution mapped \
  --comment "fixed"

4. Review Suppressions Regularly

# List suppressions expiring soon
stella unknowns list \
  --status suppressed \
  --max-age "30 days" \
  --output-format table

5. Improve Coverage Over Time

Track which categories generate the most unknowns:

stella unknowns summary --workspace-id $WS_ID

# If unmapped_purl is dominant:
# - Consider adding internal package registry
# - Work with vendors on CPE mappings
# - Contribute mappings to public databases

---

Troubleshooting

"Too many unknowns from one category"

Cause: Systemic gap in coverage

Solutions by category:

Category	Solution
unmapped_purl	Add internal package mappings; request vendor CVE IDs
checksum_miss	Submit binaries to advisory databases
language_gap	File feature request; consider SAST tools
parsing_failure	Report bug; provide sample files

"Unknowns keep reappearing after resolution"

Cause: Resolution not persisted or scope too narrow

Solution:

# Check resolution scope
stella unknowns show --id unknown-001

# Expand scope if needed
stella unknowns resolve --id unknown-001 \
  --resolution mapped \
  --scope workspace  # Not just scan

"Priority scoring seems wrong"

Cause: Automatic scoring may not reflect context

Solution: Manually adjust or provide context:

# When escalating, provide context
stella unknowns escalate --id unknown-001 \
  --reason "Handles PII despite low automatic score" \
  --severity high

---

FAQ

Q: Should unknowns block deployments?

A: It depends on your risk tolerance:

• Strict: Block on any critical unknown
• Moderate: Block on critical, warn on high
• Permissive: Warn only, track for trending

Q: How do I reduce unknowns over time?

A:

1. Contribute mappings to public databases
2. Maintain internal mapping database
3. Replace unmappable dependencies with alternatives
4. Work with vendors to publish CPE data

Q: What's the difference between suppress and resolve?

A:

• Suppress: Acknowledges risk, sets expiration, reviewed periodically
• Resolve: Permanently closes, requires evidence or justification

Q: Can I automate triage?

A: Yes, use bulk-triage with rules:

# Auto-resolve known-safe patterns
stella unknowns bulk-triage --file auto-rules.json

---

Related Documentation

• Unknowns CLI Reference
• Unknowns API Reference
• Unknowns Queue Runbook
• Score Proofs Concept Guide

---

Last Updated: 2025-12-20
Version: 1.0.0
Sprint: 3500.0004.0004