terraform-aws-loopproof-connector

The LoopProof connector. LoopProof turns your AWS Security Hub findings into Linear tickets; this module gives it the access it needs in your account, and nothing more:

• a cross-account IAM role that LoopProof's control plane assumes, with an ExternalId, to read findings and set their status and comment, and to read the tags of the resources they relate to: your ECR repositories' tags, and queries of your Config aggregators, which return any configuration an aggregator holds, not only tags;
• an EventBridge rule that forwards Security Hub's "Findings Imported V2" events to LoopProof's event bus: GuardDuty's findings at every severity, and the other findings of the severities you choose, except the findings of the accounts you exclude;
• an SSM parameter that tells LoopProof which accounts you exclude, one per accept rule, the risks you accept, and one with your settings in LoopProof, such as your SLA targets;
• one call, on the apply that creates the role, that reports the role's ARN and the Region to LoopProof, so onboarding needs no copy and paste.

Why This Module?

Connecting a third-party service to Security Hub usually means a hand-made role with broad Security Hub permissions, a long-lived ExternalId in a tfvars file, and an ARN pasted into a web form. This module:

• trusts only LoopProof's own roles for your environment, by role name and ExternalId;
• grants the two IAM actions the Security Hub v2 APIs need, and denies any update but status and comment;
• reads your ECR repositories' tags, and nothing else of ECR, and queries your Config aggregators, such as AWS Control Tower's, whose answers can hold any configuration an aggregator holds;
• treats the ExternalId and the registration token as credentials: it reads both from SSM SecureString parameters in your account, never from its inputs, so neither is ever in your code or a tfvars file, and the token is in neither the plan nor the state;
• rotates the ExternalId without a single failed AssumeRole, and without a change to your Terraform;
• registers itself once, at apply, and never calls LoopProof on a plan.

Features

• Connector role loopproof-<environment>-connector, assumable only by the control plane's loopproof-<environment>-* roles presenting one of one or two ExternalIds
• Least-privilege permissions: securityhub:GetFindings and securityhub:BatchUpdateFindings, the latter confined to the status and the comment
• Resource tags: ecr:ListTagsForResource on your account's repositories, and config:SelectAggregateResourceConfig on your account's Config aggregators in the module's Region, such as AWS Control Tower's, which returns any configuration they hold, not only tags
• Forwarding of new, updated and closed findings, GuardDuty's at every severity and the others' by OCSF severity, to a bus in another account and Region
• Account exclusion: the findings of the accounts in excluded_accounts never leave your account, and the list is published in SSM for LoopProof to read
• Accept rules: the risks you accept, written in threat_accept_rules and vulnerability_accept_rules and changed by pull request in your repository, each published in SSM for LoopProof to read and never to write
• Your settings in LoopProof: your SLA targets, thresholds, quiet window, ticket budget and review due, written in tenant_settings and changed by pull request, published in SSM for LoopProof to read, LoopProof's defaults for those you leave out
• Forwarder role that may only events:PutEvents on LoopProof's bus
• The ExternalIds read from an SSM parameter, checked before use; the registration token read as an ephemeral value
• Self-registration once, at apply, with curl, retried on connection errors and 5xx answers only
• Input validation for account ID, parameter ARNs, bus ARN, registration URL, severities, excluded accounts, the shape of each accept rule, and your settings, refusing a misspelled one

Quick Start

LoopProof's onboarding shows you the ExternalId and a registration token, once, and generates the Terraform for you, in two parts that go in the same root. It looks like this.

Part 1, the values. Two SSM SecureString parameters in the account and Region where you install the connector, created with the placeholder unset. The placeholder is write-only (value_wo), so Terraform never stores or compares the value, and never writes it again: you fill the parameters yourself, below. Write-only arguments need Terraform 1.11.

This is the beginning of the README. Read the rest at the original. Read the full README ↗