286 lines
9.1 KiB
JSON
286 lines
9.1 KiB
JSON
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"$id": "https://stellaops.org/schemas/function-map-v1.schema.json",
|
|
"title": "StellaOps Function Map v1",
|
|
"description": "Predicate schema for declaring expected call-paths for runtime→static linkage verification",
|
|
"type": "object",
|
|
"required": ["_type", "subject", "predicate"],
|
|
"properties": {
|
|
"_type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"https://stella.ops/predicates/function-map/v1",
|
|
"stella.ops/functionMap@v1"
|
|
],
|
|
"description": "Predicate type URI"
|
|
},
|
|
"subject": {
|
|
"$ref": "#/definitions/subject",
|
|
"description": "Subject artifact that this function map applies to"
|
|
},
|
|
"predicate": {
|
|
"$ref": "#/definitions/predicatePayload",
|
|
"description": "The predicate payload containing the function map definition"
|
|
}
|
|
},
|
|
"additionalProperties": false,
|
|
"definitions": {
|
|
"subject": {
|
|
"type": "object",
|
|
"required": ["purl", "digest"],
|
|
"properties": {
|
|
"purl": {
|
|
"type": "string",
|
|
"description": "Package URL of the subject artifact",
|
|
"pattern": "^pkg:[a-z]+/.+"
|
|
},
|
|
"digest": {
|
|
"type": "object",
|
|
"description": "Digest(s) of the subject artifact",
|
|
"additionalProperties": { "type": "string" },
|
|
"minProperties": 1
|
|
},
|
|
"name": {
|
|
"type": ["string", "null"],
|
|
"description": "Optional artifact name"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"predicatePayload": {
|
|
"type": "object",
|
|
"required": ["schemaVersion", "service", "expectedPaths", "coverage", "generatedAt"],
|
|
"properties": {
|
|
"schemaVersion": {
|
|
"type": "string",
|
|
"const": "1.0.0",
|
|
"description": "Schema version of this predicate"
|
|
},
|
|
"service": {
|
|
"type": "string",
|
|
"description": "Service name that this function map applies to",
|
|
"minLength": 1
|
|
},
|
|
"buildId": {
|
|
"type": ["string", "null"],
|
|
"description": "Build ID or version of the service"
|
|
},
|
|
"generatedFrom": {
|
|
"$ref": "#/definitions/generatedFrom",
|
|
"description": "References to source materials used to generate this function map"
|
|
},
|
|
"expectedPaths": {
|
|
"type": "array",
|
|
"description": "Expected call-paths that should be observed at runtime",
|
|
"items": { "$ref": "#/definitions/expectedPath" },
|
|
"minItems": 1
|
|
},
|
|
"coverage": {
|
|
"$ref": "#/definitions/coverageThresholds",
|
|
"description": "Coverage thresholds for verification"
|
|
},
|
|
"generatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "When this function map was generated"
|
|
},
|
|
"generator": {
|
|
"$ref": "#/definitions/generatorInfo",
|
|
"description": "Optional generator tool information"
|
|
},
|
|
"metadata": {
|
|
"type": ["object", "null"],
|
|
"description": "Optional metadata for extensions",
|
|
"additionalProperties": true
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"generatedFrom": {
|
|
"type": ["object", "null"],
|
|
"properties": {
|
|
"sbomRef": {
|
|
"type": ["string", "null"],
|
|
"description": "SHA256 digest of the SBOM used"
|
|
},
|
|
"staticAnalysisRef": {
|
|
"type": ["string", "null"],
|
|
"description": "SHA256 digest of the static analysis results used"
|
|
},
|
|
"binaryAnalysisRef": {
|
|
"type": ["string", "null"],
|
|
"description": "SHA256 digest of the binary analysis results used"
|
|
},
|
|
"hotFunctionPatterns": {
|
|
"type": ["array", "null"],
|
|
"description": "Hot function patterns used for filtering",
|
|
"items": { "type": "string" }
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"expectedPath": {
|
|
"type": "object",
|
|
"required": ["pathId", "entrypoint", "expectedCalls", "pathHash"],
|
|
"properties": {
|
|
"pathId": {
|
|
"type": "string",
|
|
"description": "Unique identifier for this path within the function map",
|
|
"minLength": 1
|
|
},
|
|
"description": {
|
|
"type": ["string", "null"],
|
|
"description": "Human-readable description of this call path"
|
|
},
|
|
"entrypoint": {
|
|
"$ref": "#/definitions/pathEntrypoint",
|
|
"description": "Entrypoint function that initiates this call path"
|
|
},
|
|
"expectedCalls": {
|
|
"type": "array",
|
|
"description": "Expected function calls within this path",
|
|
"items": { "$ref": "#/definitions/expectedCall" },
|
|
"minItems": 1
|
|
},
|
|
"pathHash": {
|
|
"type": "string",
|
|
"description": "Hash of the canonical path representation",
|
|
"pattern": "^sha256:[a-f0-9]{64}$"
|
|
},
|
|
"optional": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Whether this entire path is optional"
|
|
},
|
|
"strictOrdering": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Whether strict ordering of expected calls should be verified"
|
|
},
|
|
"tags": {
|
|
"type": ["array", "null"],
|
|
"description": "Optional tags for categorizing paths",
|
|
"items": { "type": "string" }
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"pathEntrypoint": {
|
|
"type": "object",
|
|
"required": ["symbol", "nodeHash"],
|
|
"properties": {
|
|
"symbol": {
|
|
"type": "string",
|
|
"description": "Symbol name of the entrypoint function",
|
|
"minLength": 1
|
|
},
|
|
"nodeHash": {
|
|
"type": "string",
|
|
"description": "Node hash for this entrypoint (PURL + normalized symbol)",
|
|
"pattern": "^sha256:[a-f0-9]{64}$"
|
|
},
|
|
"purl": {
|
|
"type": ["string", "null"],
|
|
"description": "Optional PURL of the component containing this entrypoint"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"expectedCall": {
|
|
"type": "object",
|
|
"required": ["symbol", "purl", "nodeHash", "probeTypes"],
|
|
"properties": {
|
|
"symbol": {
|
|
"type": "string",
|
|
"description": "Symbol name of the expected function call",
|
|
"minLength": 1
|
|
},
|
|
"purl": {
|
|
"type": "string",
|
|
"description": "Package URL (PURL) of the component containing this function",
|
|
"pattern": "^pkg:[a-z]+/.+"
|
|
},
|
|
"nodeHash": {
|
|
"type": "string",
|
|
"description": "Node hash for this function (PURL + normalized symbol)",
|
|
"pattern": "^sha256:[a-f0-9]{64}$"
|
|
},
|
|
"probeTypes": {
|
|
"type": "array",
|
|
"description": "Acceptable probe types for observing this function",
|
|
"items": {
|
|
"type": "string",
|
|
"enum": ["kprobe", "kretprobe", "uprobe", "uretprobe", "tracepoint", "usdt"]
|
|
},
|
|
"minItems": 1
|
|
},
|
|
"optional": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Whether this function call is optional"
|
|
},
|
|
"description": {
|
|
"type": ["string", "null"],
|
|
"description": "Optional human-readable description"
|
|
},
|
|
"functionAddress": {
|
|
"type": ["integer", "null"],
|
|
"description": "Optional function address hint for performance optimization"
|
|
},
|
|
"binaryPath": {
|
|
"type": ["string", "null"],
|
|
"description": "Optional binary path where this function is located"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"coverageThresholds": {
|
|
"type": "object",
|
|
"properties": {
|
|
"minObservationRate": {
|
|
"type": "number",
|
|
"minimum": 0.0,
|
|
"maximum": 1.0,
|
|
"default": 0.95,
|
|
"description": "Minimum observation rate required for verification to pass"
|
|
},
|
|
"windowSeconds": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"default": 1800,
|
|
"description": "Observation window in seconds"
|
|
},
|
|
"minObservationCount": {
|
|
"type": ["integer", "null"],
|
|
"minimum": 1,
|
|
"description": "Minimum number of observations required before verification can succeed"
|
|
},
|
|
"failOnUnexpected": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Whether to fail on unexpected symbols (not in the function map)"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"generatorInfo": {
|
|
"type": ["object", "null"],
|
|
"properties": {
|
|
"name": {
|
|
"type": ["string", "null"],
|
|
"description": "Name of the generator tool"
|
|
},
|
|
"version": {
|
|
"type": ["string", "null"],
|
|
"description": "Version of the generator tool"
|
|
},
|
|
"commit": {
|
|
"type": ["string", "null"],
|
|
"description": "Optional commit hash of the generator tool"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
}
|
|
}
|
|
}
|