Add aws_securityhub_finding table

aws/plugin.go

@@ -16,6 +16,7 @@ import (
 	"github.com/turbot/tailpipe-plugin-aws/tables/s3_server_access_log"
 	"github.com/turbot/tailpipe-plugin-aws/tables/vpc_flow_log"
 	"github.com/turbot/tailpipe-plugin-aws/tables/waf_traffic_log"
+	"github.com/turbot/tailpipe-plugin-aws/tables/securityhub_finding"
 	"github.com/turbot/tailpipe-plugin-sdk/plugin"
 	"github.com/turbot/tailpipe-plugin-sdk/row_source"
 	"github.com/turbot/tailpipe-plugin-sdk/table"
@@ -38,6 +39,7 @@ func init() {
 	table.RegisterTable[*guardduty_finding.GuardDutyFinding, *guardduty_finding.GuardDutyFindingTable]()
 	table.RegisterTable[*nlb_access_log.NlbAccessLog, *nlb_access_log.NlbAccessLogTable]()
 	table.RegisterTable[*s3_server_access_log.S3ServerAccessLog, *s3_server_access_log.S3ServerAccessLogTable]()
+	table.RegisterTable[*securityhub_finding.SecurityHubFinding, *securityhub_finding.SecurityHubFindingTable]()
 	table.RegisterTable[*vpc_flow_log.VpcFlowLog, *vpc_flow_log.VpcFlowLogTable]()
 	table.RegisterTable[*waf_traffic_log.WafTrafficLog, *waf_traffic_log.WafTrafficLogTable]()
 

docs/sources/aws_s3_bucket.md

@@ -77,6 +77,7 @@ The following tables define their own default values for certain source argument
 - **[aws_guardduty_finding](https://hub.tailpipe.io/plugins/turbot/aws/tables/aws_guardduty_finding#aws_s3_bucket)**
 - **[aws_nlb_access_log](https://hub.tailpipe.io/plugins/turbot/aws/tables/aws_nlb_access_log#aws_s3_bucket)**
 - **[aws_s3_server_access_log](https://hub.tailpipe.io/plugins/turbot/aws/tables/aws_s3_server_access_log#aws_s3_bucket)**
+- **[aws_securityhub_finding](https://hub.tailpipe.io/plugins/turbot/aws/tables/aws_securityhub_finding#aws_s3_bucket)**
 - **[aws_cost_and_usage_focus](https://hub.tailpipe.io/plugins/turbot/aws/tables/aws_cost_and_usage_focus#aws_s3_bucket)**
 - **[aws_cost_and_usage_report](https://hub.tailpipe.io/plugins/turbot/aws/tables/aws_cost_and_usage_report#aws_s3_bucket)**
 - **[aws_cost_optimization_recommendation](https://hub.tailpipe.io/plugins/turbot/aws/tables/aws_cost_optimization_recommendation#aws_s3_bucket)**

docs/tables/aws_securityhub_finding/index.md

@@ -0,0 +1,224 @@
+---
+title: "Tailpipe Table: aws_securityhub_finding - Query AWS Security Hub Findings"
+description: "AWS Security Hub findings provide comprehensive security findings from various AWS security services and partner integrations, including details about potential security issues and compliance violations."
+---
+
+# Table: aws_securityhub_finding - Query AWS Security Hub Findings
+
+The `aws_securityhub_finding` table allows you to query data from [AWS Security Hub findings](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings.html). This table provides detailed information about potential security issues and compliance violations detected across your AWS accounts and resources, including severity levels, compliance status, affected resources, and recommended remediation steps.
+
+## Configure
+
+Create a [partition](https://tailpipe.io/docs/manage/partition) for `aws_securityhub_finding` ([examples](https://hub.tailpipe.io/plugins/turbot/aws/tables/aws_securityhub_finding#example-configurations)):
+
+```sh
+vi ~/.tailpipe/config/aws.tpc
+```
+
+```hcl
+connection "aws" "security_account" {
+  profile = "my-security-account"
+}
+
+partition "aws_securityhub_finding" "my_findings" {
+  source "aws_s3_bucket" {
+    connection = connection.aws.security_account
+    bucket     = "aws-securityhub-findings-bucket"
+  }
+}
+```
+
+## Collect
+
+[Collect](https://tailpipe.io/docs/manage/collection) findings for all `aws_securityhub_finding` partitions:
+
+```sh
+tailpipe collect aws_securityhub_finding
+```
+
+Or for a single partition:
+
+```sh
+tailpipe collect aws_securityhub_finding.my_findings
+```
+
+## Query
+
+**[Explore example queries for this table →](https://hub.tailpipe.io/plugins/turbot/aws/queries/aws_securityhub_finding)**
+
+### High Severity Findings
+
+List all high severity security findings with detailed resource information.
+
+```sql
+select
+  tp_timestamp,
+  title,
+  types,
+  severity,
+  description,
+  tp_index as account_id,
+  region,
+  resources,
+  remediation.recommendation.text as remediation_text
+from
+  aws_securityhub_finding
+where
+  severity.normalized >= 70
+order by
+  severity.normalized desc,
+  tp_timestamp desc;
+```
+
+### Findings by Type
+
+Group findings by type with severity and temporal information.
+
+```sql
+select
+  types,
+  count(*) as finding_count,
+  round(avg(severity.normalized), 2) as avg_severity
+from
+  aws_securityhub_finding
+group by
+  types
+order by
+  finding_count desc;
+```
+
+### Recent Findings with Resource Details
+
+Examine recent security findings with comprehensive resource and remediation information.
+
+```sql
+select
+  tp_timestamp,
+  title,
+  types,
+  severity,
+  resources,
+  tp_index as account_id,
+  region,
+  workflow_state,
+  remediation.recommendation.text as remediation_text
+from
+  aws_securityhub_finding
+where
+  created_at > current_date - interval '7 days'
+order by
+  tp_timestamp desc;
+```
+
+## Example Configurations
+
+### Collect findings from an S3 bucket
+
+Collect Security Hub findings stored in an S3 bucket using the default log file format.
+
+```hcl
+connection "aws" "security_account" {
+  profile = "my-security-account"
+}
+
+partition "aws_securityhub_finding" "my_findings" {
+  source "aws_s3_bucket" {
+    connection = connection.aws.security_account
+    bucket     = "aws-securityhub-findings-bucket"
+  }
+}
+```
+
+### Collect findings from an S3 bucket with a prefix
+
+Collect Security Hub findings stored in an S3 bucket using a prefix.
+
+```hcl
+partition "aws_securityhub_finding" "my_findings_prefix" {
+  source "aws_s3_bucket" {
+    connection = connection.aws.security_account
+    bucket     = "aws-securityhub-findings-bucket"
+    prefix     = "my/prefix/"
+  }
+}
+```
+
+### Collect findings from local files
+
+You can also collect Security Hub findings from local files.
+
+```hcl
+partition "aws_securityhub_finding" "local_findings" {
+  source "file"  {
+    paths       = ["/Users/myuser/securityhub_findings"]
+    file_layout = `%{DATA}.jsonl.gz`
+  }
+}
+```
+
+### Filter high severity findings only
+
+Use the filter argument in your partition to focus on high severity findings, reducing the size of local storage.
+
+```hcl
+partition "aws_securityhub_finding" "high_severity_findings" {
+  filter = "severity.normalized >= 70"
+
+  source "aws_s3_bucket" {
+    connection = connection.aws.security_account
+    bucket     = "aws-securityhub-findings-bucket"
+  }
+}
+```
+
+### Collect findings for all accounts in an organization
+
+For a specific organization, collect findings for all accounts and regions.
+
+```hcl
+partition "aws_securityhub_finding" "my_findings_org" {
+  source "aws_s3_bucket"  {
+    connection  = connection.aws.security_account
+    bucket      = "securityhub-findings-bucket"
+    file_layout = `AWSLogs/o-aa111bb222/%{NUMBER:account_id}/SecurityHub/%{DATA:region}/%{YEAR:year}/%{MONTHNUM:month}/%{MONTHDAY:day}/%{DATA}.jsonl.gz`
+  }
+}
+```
+
+### Collect findings for a single account
+
+For a specific account, collect findings for all regions.
+
+```hcl
+partition "aws_securityhub_finding" "my_findings_account" {
+  source "aws_s3_bucket"  {
+    connection  = connection.aws.security_account
+    bucket      = "securityhub-findings-bucket"
+    file_layout = `AWSLogs/(%{DATA:org_id}/)?123456789012/SecurityHub/%{DATA:region}/%{YEAR:year}/%{MONTHNUM:month}/%{MONTHDAY:day}/%{DATA}.jsonl.gz`
+  }
+}
+```
+
+### Collect findings for a single region
+
+For all accounts, collect findings from us-east-1.
+
+```hcl
+partition "aws_securityhub_finding" "my_findings_region" {
+  source "aws_s3_bucket"  {
+    connection  = connection.aws.security_account
+    bucket      = "securityhub-findings-bucket"
+    file_layout = `AWSLogs/(%{DATA:org_id}/)?%{NUMBER:account_id}/SecurityHub/us-east-1/%{YEAR:year}/%{MONTHNUM:month}/%{MONTHDAY:day}/%{DATA}.jsonl.gz`
+  }
+}
+```
+
+## Source Defaults
+
+### aws_s3_bucket
+
+This table sets the following defaults for the [aws_s3_bucket source](https://hub.tailpipe.io/plugins/turbot/aws/sources/aws_s3_bucket#arguments):
+
+| Argument      | Default |
+|--------------|---------|
+| file_layout  | `AWSLogs/(%{DATA:org_id}/)?%{NUMBER:account_id}/SecurityHub/%{DATA:region_path}/%{YEAR:year}/%{MONTHNUM:month}/%{MONTHDAY:day}/%{DATA}.jsonl.gz` |