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:

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
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:

```bash
# 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

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

**Output:**
```yaml
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

```yaml
# .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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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:

```bash
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**:
```bash
# 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:
```bash
# 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:
```bash
# Auto-resolve known-safe patterns
stella unknowns bulk-triage --file auto-rules.json
```

---

## Related Documentation

- [Unknowns CLI Reference](../cli/unknowns-cli-reference.md)
- [Unknowns API Reference](../api/score-proofs-reachability-api-reference.md)
- [Unknowns Queue Runbook](../operations/unknowns-queue-runbook.md)
- [Score Proofs Concept Guide](./score-proofs-concept-guide.md)

---

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