mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 16:31:33 +00:00
feat: M18b Filesystem Certificate Discovery — agent scanning, server dedup, triage API
Agent-side:
- Filesystem scanner walks configured directories (CERTCTL_DISCOVERY_DIRS)
- Parses PEM (.pem, .crt, .cer, .cert) and DER (.der) certificate files
- Extracts CN, SANs, serial, issuer/subject DN, validity, key info, SHA-256 fingerprint
- Reports discoveries to control plane on startup + every 6 hours
- Skips files >1MB and private key files
Server-side:
- Migration 000006: discovered_certificates + discovery_scans tables
- Domain model: DiscoveredCertificate, DiscoveryScan, DiscoveryReport
- Three triage states: Unmanaged, Managed (claimed), Dismissed
- Repository with upsert dedup (fingerprint + agent + path)
- Service layer: process reports, claim, dismiss, list, summary
- 7 new API endpoints (84 total):
POST /agents/{id}/discoveries, GET /discovered-certificates,
GET /discovered-certificates/{id}, POST .../claim, POST .../dismiss,
GET /discovery-scans, GET /discovery-summary
- Audit trail: scan_completed, cert_claimed, cert_dismissed events
Tests: 28 new test functions (domain, handler, service layers)
Docs: README, quickstart, demo-guide, demo-advanced, architecture,
concepts, connectors, features.md all updated
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
shankar0123
@@ -0,0 +1,113 @@
|
||||
package domain
|
||||
|
||||
import (
|
||||
"time"
|
||||
)
|
||||
|
||||
// DiscoveryStatus represents the triage state of a discovered certificate.
|
||||
type DiscoveryStatus string
|
||||
|
||||
const (
|
||||
// DiscoveryStatusUnmanaged indicates a discovered cert not yet linked to a managed cert.
|
||||
DiscoveryStatusUnmanaged DiscoveryStatus = "Unmanaged"
|
||||
// DiscoveryStatusManaged indicates a discovered cert linked to a managed cert.
|
||||
DiscoveryStatusManaged DiscoveryStatus = "Managed"
|
||||
// DiscoveryStatusDismissed indicates a cert the operator chose to ignore.
|
||||
DiscoveryStatusDismissed DiscoveryStatus = "Dismissed"
|
||||
)
|
||||
|
||||
// IsValidDiscoveryStatus returns true if the status is a recognized discovery status.
|
||||
func IsValidDiscoveryStatus(s string) bool {
|
||||
switch DiscoveryStatus(s) {
|
||||
case DiscoveryStatusUnmanaged, DiscoveryStatusManaged, DiscoveryStatusDismissed:
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// DiscoveredCertificate represents a certificate found on an agent's filesystem.
|
||||
type DiscoveredCertificate struct {
|
||||
ID string `json:"id"`
|
||||
FingerprintSHA256 string `json:"fingerprint_sha256"`
|
||||
CommonName string `json:"common_name"`
|
||||
SANs []string `json:"sans"`
|
||||
SerialNumber string `json:"serial_number"`
|
||||
IssuerDN string `json:"issuer_dn"`
|
||||
SubjectDN string `json:"subject_dn"`
|
||||
NotBefore *time.Time `json:"not_before,omitempty"`
|
||||
NotAfter *time.Time `json:"not_after,omitempty"`
|
||||
KeyAlgorithm string `json:"key_algorithm"`
|
||||
KeySize int `json:"key_size"`
|
||||
IsCA bool `json:"is_ca"`
|
||||
PEMData string `json:"pem_data,omitempty"`
|
||||
SourcePath string `json:"source_path"`
|
||||
SourceFormat string `json:"source_format"`
|
||||
AgentID string `json:"agent_id"`
|
||||
DiscoveryScanID string `json:"discovery_scan_id,omitempty"`
|
||||
ManagedCertificateID string `json:"managed_certificate_id,omitempty"`
|
||||
Status DiscoveryStatus `json:"status"`
|
||||
FirstSeenAt time.Time `json:"first_seen_at"`
|
||||
LastSeenAt time.Time `json:"last_seen_at"`
|
||||
DismissedAt *time.Time `json:"dismissed_at,omitempty"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
}
|
||||
|
||||
// IsExpired returns true if the discovered certificate has expired.
|
||||
func (d *DiscoveredCertificate) IsExpired() bool {
|
||||
if d.NotAfter == nil {
|
||||
return false
|
||||
}
|
||||
return d.NotAfter.Before(time.Now())
|
||||
}
|
||||
|
||||
// DaysUntilExpiry returns the number of days until the certificate expires.
|
||||
// Returns -1 if NotAfter is not set.
|
||||
func (d *DiscoveredCertificate) DaysUntilExpiry() int {
|
||||
if d.NotAfter == nil {
|
||||
return -1
|
||||
}
|
||||
hours := time.Until(*d.NotAfter).Hours()
|
||||
return int(hours / 24)
|
||||
}
|
||||
|
||||
// DiscoveryScan represents a single discovery scan run by an agent.
|
||||
type DiscoveryScan struct {
|
||||
ID string `json:"id"`
|
||||
AgentID string `json:"agent_id"`
|
||||
Directories []string `json:"directories"`
|
||||
CertificatesFound int `json:"certificates_found"`
|
||||
CertificatesNew int `json:"certificates_new"`
|
||||
ErrorsCount int `json:"errors_count"`
|
||||
ScanDurationMs int `json:"scan_duration_ms"`
|
||||
StartedAt time.Time `json:"started_at"`
|
||||
CompletedAt *time.Time `json:"completed_at,omitempty"`
|
||||
}
|
||||
|
||||
// DiscoveryReport is the payload an agent sends after scanning its filesystem.
|
||||
type DiscoveryReport struct {
|
||||
AgentID string `json:"agent_id"`
|
||||
Directories []string `json:"directories"`
|
||||
Certificates []DiscoveredCertEntry `json:"certificates"`
|
||||
Errors []string `json:"errors,omitempty"`
|
||||
ScanDurationMs int `json:"scan_duration_ms"`
|
||||
}
|
||||
|
||||
// DiscoveredCertEntry represents a single certificate found during a filesystem scan.
|
||||
// This is the agent-side representation (no server-side IDs yet).
|
||||
type DiscoveredCertEntry struct {
|
||||
FingerprintSHA256 string `json:"fingerprint_sha256"`
|
||||
CommonName string `json:"common_name"`
|
||||
SANs []string `json:"sans"`
|
||||
SerialNumber string `json:"serial_number"`
|
||||
IssuerDN string `json:"issuer_dn"`
|
||||
SubjectDN string `json:"subject_dn"`
|
||||
NotBefore string `json:"not_before"`
|
||||
NotAfter string `json:"not_after"`
|
||||
KeyAlgorithm string `json:"key_algorithm"`
|
||||
KeySize int `json:"key_size"`
|
||||
IsCA bool `json:"is_ca"`
|
||||
PEMData string `json:"pem_data"`
|
||||
SourcePath string `json:"source_path"`
|
||||
SourceFormat string `json:"source_format"`
|
||||
}
|
||||
@@ -0,0 +1,105 @@
|
||||
package domain
|
||||
|
||||
import (
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestIsValidDiscoveryStatus(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
status string
|
||||
want bool
|
||||
}{
|
||||
{"Unmanaged", "Unmanaged", true},
|
||||
{"Managed", "Managed", true},
|
||||
{"Dismissed", "Dismissed", true},
|
||||
{"empty string", "", false},
|
||||
{"invalid status", "Unknown", false},
|
||||
{"partial match", "Manage", false},
|
||||
{"case sensitive", "unmanaged", false},
|
||||
{"lowercase managed", "managed", false},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
if got := IsValidDiscoveryStatus(tt.status); got != tt.want {
|
||||
t.Errorf("IsValidDiscoveryStatus(%q) = %v, want %v", tt.status, got, tt.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestDiscoveredCertificate_IsExpired(t *testing.T) {
|
||||
now := time.Now()
|
||||
pastTime := now.AddDate(-1, 0, 0)
|
||||
futureTime := now.AddDate(1, 0, 0)
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
notAfter *time.Time
|
||||
want bool
|
||||
}{
|
||||
{"expired certificate", &pastTime, true},
|
||||
{"valid certificate", &futureTime, false},
|
||||
{"nil NotAfter", nil, false},
|
||||
{"expires at current time (edge case)", &now, false}, // Before() = false when at same time
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
dc := &DiscoveredCertificate{
|
||||
ID: "dcert-1",
|
||||
NotAfter: tt.notAfter,
|
||||
}
|
||||
if got := dc.IsExpired(); got != tt.want {
|
||||
t.Errorf("IsExpired() = %v, want %v", got, tt.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestDiscoveredCertificate_DaysUntilExpiry(t *testing.T) {
|
||||
now := time.Now()
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
notAfter *time.Time
|
||||
wantDays int
|
||||
}{
|
||||
{"nil NotAfter", nil, -1},
|
||||
{"expires in 30 days", &time.Time{}, 0}, // placeholder, will be calculated below
|
||||
{"expires in 1 day", &time.Time{}, 1},
|
||||
{"expires in 0 days (expired)", &time.Time{}, 0},
|
||||
}
|
||||
|
||||
// Test with actual future times
|
||||
thirtyDaysFromNow := now.AddDate(0, 0, 30)
|
||||
oneDayFromNow := now.AddDate(0, 0, 1)
|
||||
pastTime := now.AddDate(0, 0, -1)
|
||||
|
||||
testCases := []struct {
|
||||
name string
|
||||
notAfter *time.Time
|
||||
wantMin int
|
||||
wantMax int
|
||||
}{
|
||||
{"nil NotAfter", nil, -1, -1},
|
||||
{"expires in 30 days", &thirtyDaysFromNow, 29, 31},
|
||||
{"expires in 1 day", &oneDayFromNow, 0, 2},
|
||||
{"already expired", &pastTime, -2, -1},
|
||||
}
|
||||
|
||||
for _, tt := range testCases {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
dc := &DiscoveredCertificate{
|
||||
ID: "dcert-2",
|
||||
NotAfter: tt.notAfter,
|
||||
}
|
||||
got := dc.DaysUntilExpiry()
|
||||
if got < tt.wantMin || got > tt.wantMax {
|
||||
t.Errorf("DaysUntilExpiry() = %d, want between %d and %d", got, tt.wantMin, tt.wantMax)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user