5146204f1b
- Introduced `sink-detect.js` with various security sink detection patterns categorized by type (e.g., command injection, SQL injection, file operations). - Implemented functions to build a lookup map for fast sink detection and to match sink calls against known patterns. - Added `package-lock.json` for dependency management.
298 lines
9.1 KiB
JSON
298 lines
9.1 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "https://stella-ops.org/schemas/finding-explainability/v2.json",
|
|
"title": "Finding Explainability Predicate Schema",
|
|
"description": "Schema for finding-explainability/v2 predicate type - vulnerability finding with assumptions, falsifiability criteria, and evidence-based confidence",
|
|
"type": "object",
|
|
"required": [
|
|
"findingId",
|
|
"vulnerabilityId",
|
|
"packageName",
|
|
"packageVersion",
|
|
"generatedAt",
|
|
"engineVersion"
|
|
],
|
|
"properties": {
|
|
"findingId": {
|
|
"type": "string",
|
|
"pattern": "^[a-zA-Z0-9-]+$",
|
|
"description": "Unique identifier for this finding"
|
|
},
|
|
"vulnerabilityId": {
|
|
"type": "string",
|
|
"pattern": "^(CVE-[0-9]{4}-[0-9]+|GHSA-.+|OSV-.+|[A-Z]+-[0-9]+)$",
|
|
"description": "The vulnerability ID (CVE, GHSA, OSV, etc.)"
|
|
},
|
|
"packageName": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Name of the affected package"
|
|
},
|
|
"packageVersion": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Version of the affected package"
|
|
},
|
|
"severity": {
|
|
"type": "string",
|
|
"enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN"],
|
|
"description": "Severity level of the vulnerability"
|
|
},
|
|
"fixedVersion": {
|
|
"type": ["string", "null"],
|
|
"description": "Version that fixes the vulnerability, if known"
|
|
},
|
|
"generatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO-8601 timestamp when this report was generated"
|
|
},
|
|
"engineVersion": {
|
|
"type": "string",
|
|
"description": "Version of the explainability engine"
|
|
},
|
|
"explanation": {
|
|
"type": "string",
|
|
"description": "Human-readable explanation of the finding"
|
|
},
|
|
"detailedNarrative": {
|
|
"type": "string",
|
|
"description": "Detailed narrative for auditor review"
|
|
},
|
|
"assumptions": {
|
|
"$ref": "#/$defs/AssumptionSet"
|
|
},
|
|
"falsifiability": {
|
|
"$ref": "#/$defs/FalsifiabilityCriteria"
|
|
},
|
|
"confidenceScore": {
|
|
"$ref": "#/$defs/EvidenceDensityScore"
|
|
},
|
|
"recommendedActions": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/$defs/RecommendedAction"
|
|
},
|
|
"description": "List of recommended remediation actions"
|
|
}
|
|
},
|
|
"additionalProperties": false,
|
|
"$defs": {
|
|
"AssumptionSet": {
|
|
"type": "object",
|
|
"description": "Collection of assumptions made during analysis",
|
|
"required": ["id", "createdAt", "assumptions"],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier for this assumption set"
|
|
},
|
|
"contextId": {
|
|
"type": ["string", "null"],
|
|
"description": "ID of the finding this assumption set belongs to"
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "When this assumption set was created"
|
|
},
|
|
"assumptions": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/$defs/Assumption"
|
|
},
|
|
"description": "List of assumptions"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"Assumption": {
|
|
"type": "object",
|
|
"description": "A single assumption made during vulnerability analysis",
|
|
"required": ["category", "key", "assumedValue", "source", "confidence"],
|
|
"properties": {
|
|
"category": {
|
|
"type": "string",
|
|
"enum": [
|
|
"CompilerFlag",
|
|
"RuntimeConfig",
|
|
"FeatureGate",
|
|
"LoaderBehavior",
|
|
"NetworkExposure",
|
|
"ProcessPrivilege",
|
|
"MemoryProtection",
|
|
"SyscallAvailability"
|
|
],
|
|
"description": "Category of the assumption"
|
|
},
|
|
"key": {
|
|
"type": "string",
|
|
"description": "Identifier for what is being assumed (e.g., flag name, config key)"
|
|
},
|
|
"assumedValue": {
|
|
"type": "string",
|
|
"description": "The value being assumed"
|
|
},
|
|
"observedValue": {
|
|
"type": ["string", "null"],
|
|
"description": "The actually observed value, if verified"
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"enum": ["Default", "StaticAnalysis", "RuntimeObservation", "UserProvided", "Inferred"],
|
|
"description": "How this assumption was derived"
|
|
},
|
|
"confidence": {
|
|
"type": "string",
|
|
"enum": ["Low", "Medium", "High", "Verified"],
|
|
"description": "Confidence level in this assumption"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"FalsifiabilityCriteria": {
|
|
"type": "object",
|
|
"description": "Criteria that would disprove or falsify the finding",
|
|
"required": ["id", "findingId", "generatedAt", "criteria"],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier for this falsifiability assessment"
|
|
},
|
|
"findingId": {
|
|
"type": "string",
|
|
"description": "ID of the finding being assessed"
|
|
},
|
|
"generatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "When this assessment was generated"
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": ["Unknown", "Falsified", "NotFalsified", "PartiallyEvaluated"],
|
|
"description": "Overall falsifiability status"
|
|
},
|
|
"summary": {
|
|
"type": ["string", "null"],
|
|
"description": "Human-readable summary of falsifiability assessment"
|
|
},
|
|
"criteria": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/$defs/FalsificationCriterion"
|
|
},
|
|
"description": "Individual falsification criteria"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"FalsificationCriterion": {
|
|
"type": "object",
|
|
"description": "A single criterion that could falsify the finding",
|
|
"required": ["type", "description", "status"],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"PackageNotPresent",
|
|
"VersionMismatch",
|
|
"CodeUnreachable",
|
|
"FeatureDisabled",
|
|
"MitigationPresent",
|
|
"NoNetworkExposure",
|
|
"InsufficientPrivileges",
|
|
"PatchApplied",
|
|
"ConfigurationPrevents",
|
|
"RuntimePrevents"
|
|
],
|
|
"description": "Type of falsification criterion"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "Human-readable description of what would falsify the finding"
|
|
},
|
|
"checkExpression": {
|
|
"type": ["string", "null"],
|
|
"description": "Machine-readable expression to check this criterion"
|
|
},
|
|
"evidence": {
|
|
"type": ["string", "null"],
|
|
"description": "Evidence supporting the criterion status"
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": ["Pending", "Satisfied", "NotSatisfied", "Inconclusive"],
|
|
"description": "Status of this criterion evaluation"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"EvidenceDensityScore": {
|
|
"type": "object",
|
|
"description": "Confidence score based on evidence density",
|
|
"required": ["score", "level"],
|
|
"properties": {
|
|
"score": {
|
|
"type": "number",
|
|
"minimum": 0.0,
|
|
"maximum": 1.0,
|
|
"description": "Numeric confidence score (0.0 to 1.0)"
|
|
},
|
|
"level": {
|
|
"type": "string",
|
|
"enum": ["Low", "Medium", "High", "Verified"],
|
|
"description": "Confidence level tier"
|
|
},
|
|
"factorBreakdown": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "number",
|
|
"minimum": 0.0,
|
|
"maximum": 1.0
|
|
},
|
|
"description": "Breakdown of contributing factors and their scores"
|
|
},
|
|
"explanation": {
|
|
"type": "string",
|
|
"description": "Human-readable explanation of the confidence assessment"
|
|
},
|
|
"improvementRecommendations": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Recommendations for improving confidence"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"RecommendedAction": {
|
|
"type": "object",
|
|
"description": "A recommended remediation action",
|
|
"required": ["priority", "action", "rationale", "effort"],
|
|
"properties": {
|
|
"priority": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"description": "Priority order (1 = highest)"
|
|
},
|
|
"action": {
|
|
"type": "string",
|
|
"description": "Description of the recommended action"
|
|
},
|
|
"rationale": {
|
|
"type": "string",
|
|
"description": "Why this action is recommended"
|
|
},
|
|
"effort": {
|
|
"type": "string",
|
|
"enum": ["Low", "Medium", "High"],
|
|
"description": "Estimated effort level"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
}
|
|
}
|
|
}
|