feat(compliance): add optional Href field to Control for linking control IDs to documentation

[unclesp1d3r]

Summary

Add an optional Href field to compliance.Control and common.ComplianceControl so that control IDs in reports can link to their relevant documentation (STIG viewer, SANS checklist, NIST references, etc.).

Problem

Control IDs like V-206694, SANS-FW-012, and FIREWALL-029 appear in audit reports but provide no direct path to the authoritative documentation. Auditors must manually search for the control definition.

Proposed Solution

Add Href string to both:

internal/compliance/interfaces.go — Control struct:

type Control struct {
    ID          string
    Href        string            `json:"href,omitempty"` // Link to control documentation
    Title       string
    // ... existing fields
}

pkg/model/enrichment.go — ComplianceControl export model:

type ComplianceControl struct {
    ID     string `json:"id,omitempty" yaml:"id,omitempty"`
    Href   string `json:"href,omitempty" yaml:"href,omitempty"`
    Status string `json:"status" yaml:"status"`
    // ... existing fields
}

Markdown rendering

In writePluginControlsTable, render the Control ID as a markdown link when Href is set:

controlID := ctrl.ID
if ctrl.Href != "" {
    controlID = fmt.Sprintf("[%s](%s)", ctrl.ID, ctrl.Href)
}

Plugin population

Each plugin sets Href on its controls:

Plugin	Example Href
STIG	https://stigviewer.com/stig/firewall_security_requirements_guide/finding/V-206694
SANS	https://www.sans.org/media/score/checklists/FirewallChecklist.pdf
Firewall	docs/firewall-security-controls-reference.md (local docs link)

Mapping

mapControls in cmd/audit_handler.go copies Href from compliance.Control to common.ComplianceControl during conversion.

Acceptance Criteria

• Href field added to compliance.Control and common.ComplianceControl
• mapControls copies Href during mapping
• Markdown report renders Control ID as [ID](href) when Href is set
• JSON/YAML exports include href field when set
• All three plugins populate Href on their controls
• model-reference.md regenerated

Related

• feat(plugin): report compliant controls alongside findings in blue mode reports #456 — parent compliance feature

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context and a proposed solution. Improve the issue title and assign the proper labels and other metadata.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

Let me first fetch the current issue details and available labels before making updates.

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== Current Issue `#508` ==="
gh issue view 508 --repo EvilBit-Labs/opnDossier --json title,body,labels,assignees,milestone,state

echo ""
echo "=== Available Labels ==="
gh label list --repo EvilBit-Labs/opnDossier --json name,description,color

echo ""
echo "=== Available Milestones ==="
gh api repos/EvilBit-Labs/opnDossier/milestones --jq '.[] | {title: .title, number: .number}'

Length of output: 102

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== Current Issue `#508` ==="
GH_TOKEN="${GITHUB_TOKEN:-}" gh issue view 508 --repo EvilBit-Labs/opnDossier --json title,body,labels,assignees,milestone,state 2>/dev/null || \
  curl -s -H "Authorization: token ${GITHUB_TOKEN:-}" \
    "https://api.github.com/repos/EvilBit-Labs/opnDossier/issues/508" | jq '{title, body, state, labels: [.labels[].name], assignees: [.assignees[].login], milestone: .milestone.title}'

echo ""
echo "=== Available Labels ==="
curl -s -H "Authorization: token ${GITHUB_TOKEN:-}" \
  "https://api.github.com/repos/EvilBit-Labs/opnDossier/labels?per_page=100" | jq '[.[] | {name, description, color}]'

echo ""
echo "=== Available Milestones ==="
curl -s -H "Authorization: token ${GITHUB_TOKEN:-}" \
  "https://api.github.com/repos/EvilBit-Labs/opnDossier/milestones?per_page=100" | jq '[.[] | {title, number}]'

Length of output: 84

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Check what auth is available
gh auth status 2>&1 || true

echo "---"
# Try listing labels directly (gh may have its own stored credentials)
gh label list --repo EvilBit-Labs/opnDossier 2>&1 || true

echo "---"
gh issue view 508 --repo EvilBit-Labs/opnDossier 2>&1 || true

Length of output: 231

---

@unclesp1d3r, the GitHub CLI isn't authenticated in the sandbox environment. Here is the fully enhanced issue content — I'll provide the exact gh commands you can run, or you can paste the content directly:

---

📝 Improved Title

feat(compliance): link Control IDs to authoritative documentation via optional Href field

---

📋 Enhanced Issue Body

## Summary

Control IDs such as `V-206694` (STIG), `SANS-FW-012`, and `FIREWALL-029` appear throughout opnDossier audit reports, but auditors currently have no direct path to the authoritative documentation that defines each control. This forces manual lookups across STIG Viewer, SANS checklists, NIST references, and local policy documents — slowing down compliance workflows and increasing the risk of misinterpretation.

This issue tracks the addition of an optional `Href` field to `compliance.Control` and `common.ComplianceControl` so that Control IDs in generated reports render as clickable hyperlinks pointing to their definitive source.

---

## Problem

Audit reports generated by opnDossier include structured compliance control data (ID, title, status, severity), but provide no navigation path to the control's source definition. Auditors must:

1. Note the Control ID from the report.
2. Manually navigate to STIG Viewer / SANS / NIST / local docs.
3. Search for the control by ID.

This friction is especially costly during large-scale audits covering dozens of controls across multiple frameworks (STIG, SANS, NIST 800-53, CIS).

---

## Proposed Solution

### 1. Extend the `Control` struct — `internal/compliance/interfaces.go`

Add an optional `Href` field for a URL or relative path to the control's documentation:

```go
type Control struct {
    ID       string
    Href     string `json:"href,omitempty"` // Link to authoritative control documentation
    Title    string
    // ... existing fields
}

2. Extend the export model — pkg/model/enrichment.go

Mirror the field in the public-facing ComplianceControl model used in JSON/YAML exports:

type ComplianceControl struct {
    ID     string `json:"id,omitempty"     yaml:"id,omitempty"`
    Href   string `json:"href,omitempty"   yaml:"href,omitempty"`
    Status string `json:"status"           yaml:"status"`
    // ... existing fields
}

3. Copy Href during mapping — cmd/audit_handler.go

In mapControls, copy Href from compliance.Control to common.ComplianceControl:

func mapControls(controls []compliance.Control) []common.ComplianceControl {
    mapped := make([]common.ComplianceControl, 0, len(controls))
    for _, ctrl := range controls {
        mapped = append(mapped, common.ComplianceControl{
            ID:     ctrl.ID,
            Href:   ctrl.Href, // propagate documentation link
            Status: ctrl.Status,
            // ... existing fields
        })
    }
    return mapped
}

4. Render as markdown hyperlink — writePluginControlsTable

When Href is set, render the Control ID as a markdown link:

controlID := ctrl.ID
if ctrl.Href != "" {
    controlID = fmt.Sprintf("[%s](%s)", ctrl.ID, ctrl.Href)
}

5. Populate Href in each plugin

Plugin	Example Href Value
STIG	https://stigviewer.com/stig/firewall_security_requirements_guide/finding/V-206694
SANS	https://www.sans.org/media/score/checklists/FirewallChecklist.pdf
Firewall	docs/firewall-security-controls-reference.md

---

Impact

Artifact	Change
Markdown report	Control IDs rendered as [V-206694](https://stigviewer.com/...)
JSON export	"href" field included when set (omitempty)
YAML export	href: field included when set (omitempty)
model-reference.md	Regenerated to document new field

---

Acceptance Criteria

• Href field added to compliance.Control (internal/compliance/interfaces.go)
• Href field added to common.ComplianceControl (pkg/model/enrichment.go)
• mapControls in cmd/audit_handler.go propagates Href from internal to export model
• writePluginControlsTable renders [ID](Href) markdown link when Href is non-empty
• JSON and YAML exports include href when set (omitempty on both)
• STIG plugin populates Href per control
• SANS plugin populates Href per control
• Firewall plugin populates Href per control
• model-reference.md regenerated to reflect new field
• No regression in existing compliance report output when Href is empty

---

Related Issues / References

• #456 — parent compliance feature
• STIG Viewer
• SANS Firewall Checklist
• NIST SP 800-53

---

### 🏷️ Suggested Labels & Metadata

| Field       | Value |
|-------------|-------|
| **Title**   | `feat(compliance): link Control IDs to authoritative documentation via optional Href field` |
| **Labels**  | `enhancement`, `compliance`, `reporting`, `good first issue` |
| **Assignee**| `unclesp1d3r` |
| **Milestone**| Next applicable milestone (e.g., `v1.x`) |

---

### ⚙️ Apply via `gh` CLI

Once authenticated, you can apply this with:

```bash
gh issue edit 508 --repo EvilBit-Labs/opnDossier \
  --title "feat(compliance): link Control IDs to authoritative documentation via optional Href field" \
  --body-file /path/to/enhanced-body.md \
  --add-label "enhancement,compliance,reporting"

The label names may differ depending on what's defined in the repo — verify with gh label list --repo EvilBit-Labs/opnDossier first.