Finding Format
A finding is an instance of a signal observed in a specific environment. While signals are abstract definitions, findings are concrete observations that security tools emit when they detect conditions described by signals.
Findings are not part of the registry. The CSE registry contains signal definitions and mappings. Findings are created by tools that implement CSE and are stored in your own systems.
Schema Overview
Findings follow a standardized structure that enables interoperability between tools. Any tool emitting CSE-compatible findings should conform to this schema.
{
"$schema": "https://cseregistry.org/schemas/finding.schema.json",
"id": "f-2024-001-aws-s3-encrypt",
"signal_id": "CSE-HIPAA-TECH-ENCRYPT-REST-001",
"observed_at": "2024-12-28T14:30:00Z",
"status": "open",
"severity_override": null,
"artifact": {
"type": "cloud_resource",
"provider": "aws",
"service": "s3",
"resource_id": "arn:aws:s3:::patient-records-bucket",
"region": "us-east-1"
},
"evidence": {
"encryption_enabled": false,
"bucket_name": "patient-records-bucket",
"default_encryption": null
},
"source": {
"tool": "aws-config",
"tool_version": "1.0.0",
"rule": "s3-bucket-server-side-encryption-enabled",
"scan_id": "scan-abc123def456"
},
"metadata": {
"account_id": "123456789012",
"environment": "production",
"owner": "platform-team"
}
}Required Fields
id
| Type | string |
| Format | Tool-defined unique identifier |
A unique identifier for this finding instance. The format is defined by the emitting tool but should be unique within that tool's context.
signal_id
| Type | string |
| Pattern | ^CSE-[A-Z0-9]+(-[A-Z0-9]+)*-[0-9]{3}$ |
The CSE signal ID that this finding is an instance of. Must reference a valid signal in the CSE registry.
observed_at
| Type | string (ISO 8601) |
| Example | 2024-12-28T14:30:00Z |
The timestamp when the condition was observed. Should be in UTC with timezone indicator.
status
| Type | string (enum) |
| Values | open, resolved, accepted, suppressed |
| Status | Description |
|---|---|
| open | Finding is active and requires attention |
| resolved | The underlying condition has been remediated |
| accepted | Risk has been formally accepted (with justification) |
| suppressed | Finding is hidden (false positive, duplicate, etc.) |
artifact
| Type | object |
Information about the resource or artifact where the condition was observed. The structure varies by artifact type.
Artifact Types
| Type | Description | Key Fields |
|---|---|---|
| cloud_resource | Cloud provider resource | provider, service, resource_id, region |
| configuration | Configuration file | file_path, file_type, repository |
| container | Container image | image, registry, tag, digest |
| code | Source code location | file_path, line_start, line_end, commit |
| host | Server or workstation | hostname, ip_address, os, os_version |
| network | Network resource | cidr, port, protocol, direction |
Cloud Resource Artifact Example
"artifact": {
"type": "cloud_resource",
"provider": "aws",
"service": "ec2",
"resource_id": "sg-0abc123def456789",
"resource_type": "security_group",
"region": "us-east-1",
"account_id": "123456789012",
"tags": {
"Name": "web-servers-sg",
"Environment": "production"
}
}Configuration Artifact Example
"artifact": {
"type": "configuration",
"file_path": "terraform/modules/network/security_groups.tf",
"file_type": "terraform",
"repository": "github.com/acme/infrastructure",
"branch": "main",
"commit": "abc123def456"
}Optional Fields
severity_override
| Type | string | null |
| Values | critical, high, medium, low, info |
Allows the emitting tool or operator to override the signal's default severity based on context. If null, the signal's default severity applies.
evidence
| Type | object |
Structured evidence supporting the finding. The schema is flexible but should include the specific data points that led to the detection.
"evidence": {
"encryption_enabled": false,
"bucket_versioning": true,
"public_access_blocked": true,
"evaluated_rules": [
"sse_algorithm_check",
"kms_key_check"
],
"raw_config": {
"ServerSideEncryptionConfiguration": null
}
}source
| Type | object |
Information about the tool or process that generated this finding.
"source": {
"tool": "aws-config",
"tool_version": "2024.1.0",
"rule": "s3-bucket-server-side-encryption-enabled",
"rule_version": "1.0",
"scan_id": "scan-abc123def456",
"scan_type": "scheduled"
}metadata
| Type | object |
Additional context about the finding for organizational or operational use.
"metadata": {
"account_id": "123456789012",
"account_name": "production",
"environment": "production",
"owner": "platform-team",
"cost_center": "engineering",
"criticality": "high",
"data_classification": "phi"
}related_findings
References to related findings for correlation:
"related_findings": [
{
"finding_id": "f-2024-002-aws-s3-logging",
"relationship": "same_resource"
},
{
"finding_id": "f-2024-003-tf-s3-encrypt",
"relationship": "same_issue"
}
]remediation
Tracking information for remediation efforts (populated after initial detection):
"remediation": {
"assigned_to": "john.doe@example.com",
"due_date": "2024-01-15",
"ticket_url": "https://jira.example.com/browse/SEC-1234",
"notes": "Scheduled for next maintenance window"
}Complete Example
{
"$schema": "https://cseregistry.org/schemas/finding.schema.json",
"id": "f-2024-001-aws-sg-ssh",
"signal_id": "CSE-CMMC-COMMS-UNRESTRICTED-SSH-001",
"observed_at": "2024-12-28T14:32:00Z",
"status": "open",
"severity_override": "critical",
"artifact": {
"type": "cloud_resource",
"provider": "aws",
"service": "ec2",
"resource_id": "sg-0abc123def456789",
"resource_type": "security_group",
"region": "us-east-1",
"account_id": "123456789012",
"tags": {
"Name": "legacy-admin-access",
"Environment": "production"
}
},
"evidence": {
"ingress_rules": [
{
"protocol": "tcp",
"port": 22,
"source": "0.0.0.0/0",
"description": "SSH access"
}
],
"rule_count": 5,
"attached_instances": 3
},
"source": {
"tool": "cloud-security-scanner",
"tool_version": "3.2.1",
"rule": "open-ssh-check",
"scan_id": "scan-xyz789",
"scan_type": "continuous"
},
"metadata": {
"account_id": "123456789012",
"account_name": "prod-workloads",
"environment": "production",
"owner": "legacy-team",
"criticality": "high"
},
"related_findings": [
{
"finding_id": "f-2024-002-tf-sg-ssh",
"relationship": "same_issue"
}
]
}Working with Findings
Emitting Findings
Tools that detect conditions should emit findings referencing CSE signals:
import json
from datetime import datetime
def create_finding(signal_id, artifact, evidence):
"""Create a CSE-compatible finding."""
return {
"id": f"f-{datetime.now().strftime('%Y%m%d%H%M%S')}-{artifact['resource_id'][-8:]}",
"signal_id": signal_id,
"observed_at": datetime.utcnow().isoformat() + "Z",
"status": "open",
"artifact": artifact,
"evidence": evidence,
"source": {
"tool": "my-security-scanner",
"tool_version": "1.0.0",
"scan_id": generate_scan_id()
}
}
# Example usage
finding = create_finding(
signal_id="CSE-HIPAA-TECH-ENCRYPT-REST-001",
artifact={
"type": "cloud_resource",
"provider": "aws",
"service": "s3",
"resource_id": "arn:aws:s3:::my-bucket"
},
evidence={
"encryption_enabled": False
}
)
print(json.dumps(finding, indent=2))Validating Findings
# Validate a finding against the schema
ajv validate -s finding.schema.json -d my-finding.json