Documentation
¶
Overview ¶
Package templates is the single source of truth for the Valkey contracts that bind the scanner stack together. Every component that reads or writes agent vulnerability templates or NSE scripts should import the helpers here instead of hand-rolling key strings or JSON envelopes.
Producers/consumers as of go-api v0.0.18:
- sirius-api (handlers/agent_template_handler.go) - writes custom templates
- app-agent (internal/template/valkey) - writes built-in + reads everything
- app-scanner (internal/nse) - writes NSE script content + manifest
- sirius-ui (utils/nseScriptIds.ts) - mirrors CanonicalScriptID
PR 7 of the scanner-templates-fix sprint migrates each of those callers off their local copies and onto these helpers.
Index ¶
- Constants
- func AgentTemplateKey(id string, isCustom bool) string
- func AgentTemplateMetaKey(id string) string
- func CanonicalScriptID(id string) string
- func EncodeMeta(r *TemplateRecord) ([]byte, error)
- func EncodeNseManifest(m *NseManifest) ([]byte, error)
- func EncodeNseScript(r *NseScriptRecord) ([]byte, error)
- func EncodeTemplate(r *TemplateRecord) ([]byte, error)
- func NseScriptKey(id string) string
- func SHA256Hex(b []byte) string
- func WriteNseManifest(ctx context.Context, kv kvWriter, m *NseManifest) error
- func WriteNseScript(ctx context.Context, kv kvWriter, id string, r *NseScriptRecord) error
- func WriteTemplate(ctx context.Context, kv interface{ ... }, r *TemplateRecord) error
- type NseManifest
- type NseManifestEntry
- type NseScriptMeta
- type NseScriptRecord
- type TemplateRecord
Constants ¶
const ( KeyAgentTemplateStandardPrefix = "template:standard:" KeyAgentTemplateCustomPrefix = "template:custom:" KeyAgentTemplateMetaPrefix = "template:meta:" KeyAgentTemplateManifest = "template:manifest" KeyAgentTemplateRepoManifest = "template:repo-manifest" KeyAgentTemplateVersionPrefix = "template:version:" )
Agent vulnerability template keys.
Layout (mirrors app-agent/internal/template/valkey/storage.go):
template:standard:<id> - built-in templates synced from a Git repo, JSON envelope (TemplateInfo) template:custom:<id> - operator-uploaded templates, JSON envelope (TemplateInfo) template:meta:<id> - per-template metadata snapshot used for fast enumeration; same shape as the envelope but with `content` omitted template:manifest - global manifest snapshot (TemplateManifest) template:repo-manifest - per-repository manifest map template:version:<id> - version-pinning index (reserved)
const ( KeyNseScriptPrefix = "nse:script:" KeyNseScriptMetaPrefix = "nse:meta:" KeyNseManifest = "nse:manifest" KeyNseRepoManifest = "nse:repo-manifest" )
NSE script keys.
Layout (mirrors app-scanner/internal/nse/types.go):
nse:script:<id> - script content + metadata (ScriptContent envelope) nse:meta:<id> - lightweight script metadata (reserved; not all writers populate today) nse:manifest - global manifest of all scripts (Manifest) nse:repo-manifest - repository list driving the sync (RepositoryList)
IDs in this namespace are always canonical: no `.nse` suffix, no directory prefix. Use CanonicalScriptID to normalize anything that crosses a process boundary.
Variables ¶
This section is empty.
Functions ¶
func AgentTemplateKey ¶
AgentTemplateKey returns the Valkey key for a template's content envelope. `isCustom` selects the namespace; pass true for operator-uploaded templates and false for repo-synced ones.
func AgentTemplateMetaKey ¶
AgentTemplateMetaKey returns the Valkey key for a template's metadata snapshot. Always under the same `template:meta:` namespace regardless of whether the source is custom or standard.
func CanonicalScriptID ¶
CanonicalScriptID normalizes an NSE script identifier so producers and consumers agree on the Valkey key.
Rules (mirrors sirius-ui/src/utils/nseScriptIds.ts and the helper originally introduced in PR 1 of the scanner-templates-fix sprint at app-scanner/internal/nse/sync.go):
- Strip any directory prefix ("scripts/foo/bar.nse" -> "bar.nse").
- Strip a trailing ".nse" extension ("bar.nse" -> "bar").
- Pass "" and the wildcard "*" through unchanged so callers can use them as sentinels in patterns / KEYS commands.
CanonicalScriptID is idempotent: CanonicalScriptID(CanonicalScriptID(x)) == CanonicalScriptID(x).
func EncodeMeta ¶
func EncodeMeta(r *TemplateRecord) ([]byte, error)
EncodeMeta is a convenience for `EncodeTemplate(r.Meta())`. Use this when persisting the meta snapshot to keep call sites symmetric with the template-content path.
func EncodeNseManifest ¶
func EncodeNseManifest(m *NseManifest) ([]byte, error)
EncodeNseManifest marshals the manifest to JSON.
func EncodeNseScript ¶
func EncodeNseScript(r *NseScriptRecord) ([]byte, error)
EncodeNseScript marshals a script envelope to JSON.
func EncodeTemplate ¶
func EncodeTemplate(r *TemplateRecord) ([]byte, error)
EncodeTemplate marshals the envelope to JSON. Wraps json.Marshal so callers don't have to redeclare the error context.
func NseScriptKey ¶
NseScriptKey returns the Valkey key for a script's content envelope. The id is canonicalized so callers can safely pass anything coming off the wire (manifest paths, UI input, etc.).
func SHA256Hex ¶
SHA256Hex returns the hex-encoded SHA-256 of the supplied bytes. Callers building a TemplateRecord should populate Checksum from this helper so the field stays consistent across components.
func WriteNseManifest ¶
func WriteNseManifest(ctx context.Context, kv kvWriter, m *NseManifest) error
WriteNseManifest persists the manifest with canonicalized map keys. The original Scripts map is left untouched on the caller's side.
func WriteNseScript ¶
func WriteNseScript(ctx context.Context, kv kvWriter, id string, r *NseScriptRecord) error
WriteNseScript persists a script envelope. Canonicalizes the key so producers don't accidentally write `.nse`-suffixed entries.
func WriteTemplate ¶
func WriteTemplate(ctx context.Context, kv interface { kvReader kvWriter }, r *TemplateRecord) error
WriteTemplate persists the envelope and its meta snapshot atomically from the caller's perspective: if the meta write fails the envelope is rolled back so an enumerator never sees a custom record without a matching meta entry.
Types ¶
type NseManifest ¶
type NseManifest struct {
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description"`
Scripts map[string]NseManifestEntry `json:"scripts"`
}
NseManifest mirrors app-scanner/internal/nse.Manifest. The Scripts map is keyed by canonical id.
func DecodeNseManifest ¶
func DecodeNseManifest(data []byte) (*NseManifest, error)
DecodeNseManifest parses a JSON envelope back into an NseManifest.
func ReadNseManifest ¶
func ReadNseManifest(ctx context.Context, kv kvReader) (*NseManifest, error)
ReadNseManifest fetches and decodes the manifest.
type NseManifestEntry ¶
type NseManifestEntry struct {
Name string `json:"name"`
Path string `json:"path"`
Protocol string `json:"protocol"`
}
NseManifestEntry mirrors app-scanner/internal/nse.Script. Manifest keys are canonicalized (no .nse suffix); Path preserves whatever the on-disk repository expects.
type NseScriptMeta ¶
type NseScriptMeta struct {
Author string `json:"author"`
Tags []string `json:"tags"`
Description string `json:"description"`
}
NseScriptMeta carries lightweight script metadata (author, tags, description). Mirrors app-scanner/internal/nse.Metadata.
type NseScriptRecord ¶
type NseScriptRecord struct {
Content string `json:"content"`
Metadata NseScriptMeta `json:"metadata"`
UpdatedAt int64 `json:"updatedAt"`
}
NseScriptRecord is the envelope persisted at nse:script:<canonical-id>. Field names and JSON tags match the legacy app-scanner ScriptContent type so this package can be a drop-in for that producer.
func DecodeNseScript ¶
func DecodeNseScript(data []byte) (*NseScriptRecord, error)
DecodeNseScript parses a JSON envelope back into an NseScriptRecord.
func ReadNseScript ¶
func ReadNseScript(ctx context.Context, kv kvReader, id string) (*NseScriptRecord, error)
ReadNseScript fetches and decodes a script envelope. Canonicalizes the id before lookup so callers can safely pass raw input.
type TemplateRecord ¶
type TemplateRecord struct {
ID string `json:"id"`
Version string `json:"version"`
Checksum string `json:"checksum"`
Size int64 `json:"size"`
Severity string `json:"severity"`
Platforms []string `json:"platforms"`
DetectionType string `json:"detection_type"`
Author string `json:"author"`
Created time.Time `json:"created"`
Updated time.Time `json:"updated"`
VulnerabilityIDs []string `json:"vulnerability_ids"`
IsCustom bool `json:"is_custom"`
Content []byte `json:"content,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
TemplateRecord is the agent vulnerability template envelope persisted at template:standard:<id> and template:custom:<id>. Field names and JSON tags MUST match app-agent/internal/template/valkey.TemplateInfo because the agent reads those keys directly.
`Content` is the raw template bytes (typically YAML). On the JSON wire the field encodes as base64 by Go convention for []byte; agents expect that encoding.
func DecodeTemplate ¶
func DecodeTemplate(data []byte) (*TemplateRecord, error)
DecodeTemplate parses a JSON envelope back into a TemplateRecord.
func ReadTemplate ¶
func ReadTemplate(ctx context.Context, kv kvReader, id string) (*TemplateRecord, error)
ReadTemplate fetches and decodes a template envelope. Tries the custom namespace first, then standard, so callers don't have to know which side wrote it. Returns (nil, nil) when neither key exists.
func ReadTemplateMeta ¶
func ReadTemplateMeta(ctx context.Context, kv kvReader, id string) (*TemplateRecord, error)
ReadTemplateMeta fetches and decodes the meta snapshot for id. Returns (nil, nil) when the key is absent.
func (TemplateRecord) Meta ¶
func (r TemplateRecord) Meta() TemplateRecord
Meta returns a copy of the record with Content stripped, suitable for writing to template:meta:<id>. The meta record carries enough info for fast enumeration without pulling the whole template body.
Source Files