Ingest Data from a Custom Finding Source

To configure custom finding sources in Opus and ensure proper data ingestion, follow the steps below and adhere to the specified data scheme:

Custom Source Configuration Steps:

1. Access the Integration Menu:

  • Go to the integration menu.
  • Under the "finding sources" section, click on "Custom finding source".

2. Webhook Configuration:

  • A popup window will appear for webhook configuration.
  • Name the webhook.
  • Select 'none' for the scope or choose the desired scope.
  • Click on the 'connect' button

3. Enable the Finding Source:

  • After the webhook is set up, you will see an option to enable the finding source.
  • Click on the "enable finding source" button.
  • Copy the displayed webhook URL.
  • Click 'update' to save the changes.

Data Scheme for Ingestion:

After setting up the custom finding source, ensure that the data sent to the webhook follows the specified JSON structure as outlined below.

Schema Attribute Breakdown

FieldTypeValueDescription
typeStringType of the eventActs as the rule generator of the finding. Group by risk is grouped around this value.
externalIdString Unique id of the findingImportant for resolving existing findings in Opus and for avoiding creating duplications.
titleStringTitle for finding pageThe title of the finding
descriptionStringDescription for finding pageThe description of the finding
createdAtdatetimeCreation date of the issue on the finding source.

2024-01-30T13:12:06.729Z
The finding detection time
resourceIdStringUnique id of the resource (e.g., Aws ARN, Azure URI, Gcp Id, Hostname)Important for cloud to code purposes, ensure to provide the exact vendor id. For code, provide the code path.
resourceNameStringName of the resourceName of the resource
resourceTypeStringType of the resource (e.g., AwsEc2Instance, AzureVm...)Flexible value, logos are loaded according to Opus reserved types (See below for a complete list of Resource Types)
severityEnumSeverity of the issue (e.g., Informational, Low, High, Critical)Provides the sensor score as an input for the risk score computation.
cloudProviderStringProvider of the issue (e.g., AWS, AZURE, GCP, Github, GitLab...)Cloud or code provider vendor
findingSourceStringSource of the finding (e.g., Orca, Wiz, Snyk)Your desired source name, with the ability to filter by it.
workspaceIdStringCloud account unique id (e.g., Aws account id, Azure subscription id, Gcp project id, Github/Gitlab repo id)Used for matching the finding to the proper workspace and for the correct Business Unit/service.
categoryStringCategory of the finding (e.g., Vulnerabilities, Code Vulnerability, Data Protection...)Flexible text, with the ability to filter by it.
externalStatusEnumExternal status on finding source (e.g., Open, Resolved)Incase finding with the same externalId exist in Opus with externalStatus Resolved the finding is resolved in Opus.
layerEnumDetection layer of the finding (e.g., Runtime, Artifact, Code, Runtime)Detection layer of the finding.
findingTypeEnumType of the finding (e.g Code Vulnerability, On-Prem Vulnerability
Cloud Vulnerability, Cloud Misconfiguration, Web Application Vulnerability)
Type of the finding.

Example #1 - Cloud Layer

{  
    "type": "standards/aws-foundational-security-best-practices/v/1.0.0/S3.2",  
    "title": "S3 buckets allow public read access",  
    "description": "This AWS control checks whether your S3 buckets allow public read access by evaluating the Block Public Access settings, the bucket policy, and the bucket access control list (ACL).",  
    "createdAt": "2023-09-10T11:25:53.000Z",  
    "resourceId": "arn:aws:s3:::802256041567-bucket-8",  
    "resourceName": "bucket-8",  
    "resourceType": "AwsS3Bucket",  
    "severity": "HIGH",  
    "cloudProvider": "AWS",  
    "findingSource": "MySourceName",  
    "workspaceId": "802256041567",  
    "category": "Data Protection",  
    "externalId": "arn:aws:securityhub:us-east-1:802256041567:security-control/S3.2/finding/80225604156701",  
    "externalStatus": "Open",  
    "layer": "Runtime",  
    "findingType": "Cloud Misconfiguration",  
    "resourceTags": {  
        "Owner": "[[email protected]](mailto:[email protected])",  
        "Env": "Dev"  
    }  
  

Example #2 - Code Layer

{  
        "type": "aws_access_key_id",  
        "title": "Possibly active secret",  
        "description": "Possibly active secret\\nPath: terraform/aws/ec22.tf\\nStart line: 15\\nEnd line: 15 \\n Blob SHA: 4e7b92c3e89b5e7229a208379fc465b03749ec6c\\nCommit SHA: 1e25f4212a1c4e176bb122531a7ebd5969815367\\nRepository Info: \\nname: OpusSecurityLab/terragoat",  
        "createdAt": "2024-01-09T15:13:31Z",  
        "resourceId": "OpusSecurityLab/terragoat/terraform/aws/ec22.tf",  
        "resourceName": "terraform/aws/ec22.tf",  
        "resourceType": "CodeFile",  
        "severity": "MEDIUM",  
        "cloudProvider": "Github",  
        "workspaceId": "OpusSecurityLab/terragoat",  
        "findingSource": "Github Advanced Security",  
        "externalId": "2",  
        "externalStatus": "Open",  
        "category": "Secerts",  
        "layer": "Code",  
        "findingType": "Code Vulnerability",  
}

Update Finding Status

Opus provides the functionality to synchronize the finding status with changes occurring in the external source. By dispatching an update event to Opus, and adjusting the externalStatus field to the value 'Resolved', the status within Opus will be updated to reflect this change.

Example 3- Resolved Status Update

{  
    "type": "standards/aws-foundational-security-best-practices/v/1.0.0/S3.2",  
    "title": "S3 buckets allow public read access",  
    "description": "This AWS control checks whether your S3 buckets allow public read access by evaluating the Block Public Access settings, the bucket policy, and the bucket access control list (ACL).",  
    "createdAt": "2023-09-10T11:25:53.000Z",  
    "resourceId": "arn:aws:s3:::802256041567-bucket-8",  
    "resourceName": "bucket-8",  
    "resourceType": "AwsS3Bucket",  
    "severity": "HIGH",  
    "cloudProvider": "AWS",  
    "findingSource": "MySourceName",  
    "workspaceId": "802256041567",  
    "category": "Data Protection",  
    "externalId": "arn:aws:securityhub:us-east-1:802256041567:security-control/S3.2/finding/80225604156701",  
    "externalStatus": "Resolved",
    "layer": "Runtime",  
    "findingType": "Cloud Misconfiguration",  
    "resourceTags": {  
        "Owner": "[[email protected]](mailto:[email protected])",  
        "Env": "Dev"  
    }  
  }

.

Supported Rescource Types
AccessRoleBinding
AwsAccount
AwsAsg
AwsAthenaWorkGroup
AwsAutoScalingAutoScalingGroup
AwsAutoScalingGroup
AwsCertificate
AwsCloudFormationStack
AwsCloudFront
AwsCloudTrail
AwsCloudTrailTrail
AwsEc2EbsSnapshot
AwsEc2EbsVolume
AwsEc2ElasticIpAddress
AwsEc2Elb
AwsEc2Elbv2
AwsEc2Instance
AwsEc2LaunchTemplate
AwsEc2NetworkAcl
AwsEc2NetworkInterface
AwsEc2SecurityGroup
AwsEc2Snapshot
AwsEc2Subnet
AwsEc2Volume
AwsEc2Vpc
AwsEc2VpcEndpoint
AwsEcrContainerImage
AwsEcrRepository
AwsEcsCluster
AwsEcsContainerInstance
AwsEcsService
AwsEcsTaskDefinition
AwsEfsAccessPoint
AwsEfsFileSystem
AwsEksCluster
AwsEksNodegroup
AwsElbv2LoadBalancer
AwsGlueDataCatalog
AwsIamAccessKey
AwsIamGroup
AwsIamManagedPolicy
AwsIamPasswordPolicy
AwsIamPolicy
AwsIamRole
AWSIAMRole
AwsIamUser
AwsKmsKey
AwsLambdaFunction
AwsRdsDbCluster
AwsRdsDbClusterSnapshot
AwsRdsDbInstance
AwsRdsDbInstanceGabay
AwsRdsDbInstanceSnapshot
AwsRdsDbSnapshot
AwsRegion
AwsRoute53HostedZone
AwsS3Bucket
AwsSecretsManagerSecret
AwsSnsSubscription
AwsSnsTopic
AwsSqsQueue
AwsSsmAssociationCompliance
AwsSubnet
AwsSystemsManagerParameter
AwsUser
AwsVpc
AzureAcrContainerImage
AzureAcrImage
AzureComputeVm
AzureContainerRegistry
AzureDisk
AzureFunction
AzureNetworkInterface
AzureNetworkSecurityGroup
AzureNetworkSecurityGroupRule
AzureNetworkWatcher
AzurePostgresDbServer
AzureRoleAssignment
AzureSotrageAccount
AzureSqlDbServer
AzureStorageAccount
AzureStorageContainer
AzureSubscription
AzureUser
AzureVNet
AzureWebAppService
CloudFormationFile
CodeFile
Container
Dockerfile
GcpGcrContainerImage
GcpGcrImage
GcpIamServiceAccount
GcpNewDomain
GcpSqlInstance
GcpStorageBucket
GcpSubnet
GcpVmInstance
GcpVpc
GcpVpcSubnet
PackageManager
TerraformFile
URL
WorkStation