Amazon Inspector ExecModule

Overview

The Amazon Inspector ExecModule brings AWS vulnerability findings and scan-coverage evidence into ValkyrAI as bounded, governed workflow data. Teams can discover active findings, prioritize high and critical risk, retrieve focused enrichment for exact finding ARNs, measure which EC2, ECR, and Lambda resources are covered, inspect regional account activation, and understand member-account or organization posture without placing AWS credentials in workflow payloads.

The connector is designed for remediation orchestration rather than bulk security-data export. Finding lists normalize the identity, severity, status, scoring, fix, exploit, timing, and affected-resource fields teams need to make routing decisions. Detailed reads return bounded risk, EPSS, CWE, reference, tool, and technique fields for an exact batch of findings. Raw SDK objects, provider exception text, resource tags, deep evidence objects, and credentials are excluded.

Every operation in this release is read-only and repeatable. Lists are bounded, provider pagination is explicit, transient reads use controlled retries, and all operations bind a verified IntegrationAccount. Raw access keys, secret keys, session tokens, authorization headers, endpoint overrides, unknown fields, malformed ARNs, and invalid account identifiers are rejected before any AWS request.

Usage

Activate Amazon Inspector in every AWS region the workflow must assess.
Create a least-privilege AWS identity containing only the Inspector read actions the workflow needs.
Store its access-key pair in a ValkyrAI IntegrationAccount, verify it, and keep it in READY status.
Add AwsInspectorModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
Set the exact AWS region, select one supported operation, and add narrow filters or identifiers.
Use limit for a deliberate total bound. Enable returnAll only when the downstream workflow can safely process every page up to that bound.
Preserve findingArn, affected resource identity, and updatedAt when deduplicating remediation work.

Amazon Inspector is regional. A successful result in one region does not prove the service is activated or complete elsewhere. This release does not enable or disable scanning, change organization configuration, associate or disassociate accounts, create suppression filters, update EC2 deep inspection, or mutate findings.

Inputs

Input	Type	Required	Default	Description
`operation`	string	Yes	—	One supported Amazon Inspector read operation.
`region`	string	Yes	—	Exact AWS region such as `us-west-2`.
`nextToken`	string	No	—	Opaque continuation token returned by Inspector.
`limit`	integer	No	`100`	Total list bound from 1 to 1,000.
`returnAll`	boolean	No	`false`	Follow provider pages until `limit` or exhaustion.
`accountIds`	array	Account status	—	One to 100 unique 12-digit AWS account IDs.
`accountId`	string	Member detail	—	One exact 12-digit member account ID.
`findingArns`	array	Finding detail	—	One to 10 unique Amazon Inspector finding ARNs.
`findingStatuses`	array	No	—	Up to `ACTIVE`, `SUPPRESSED`, and `CLOSED`.
`severities`	array	No	—	Up to `INFORMATIONAL`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`, and `UNTRIAGED`.
`resourceTypes`	array	No	—	Finding resources: EC2 instance, ECR image or repository, and Lambda function.
`coverageResourceTypes`	array	No	—	The same bounded resource families for coverage operations.
`groupBy`	string	Coverage statistics	`RESOURCE_TYPE`	`SCAN_STATUS_CODE`, `SCAN_STATUS_REASON`, `ACCOUNT_ID`, `RESOURCE_TYPE`, or `ECR_REPOSITORY_NAME`.
`onlyAssociated`	boolean	No	`true`	Limit `list_members` to associated accounts.

Unknown or operation-inappropriate fields are rejected. Lists reject duplicates, unsupported enum values, and values outside documented size and character bounds.

Outputs

Every operation returns a stable envelope:

Output	Description
`status`	`success` or `error`.
`operation`	Normalized operation name.
`attempts`	Provider calls, including pages and safe read retries.
`resultType`	Result family such as `findings`, `coverage`, `coverage_statistics`, or `member`.
`items` / `count`	Bounded normalized list results and returned count.
`pages` / `hasMore` / `nextToken`	Pagination evidence for list operations.
`data`	Account status, finding detail, member detail, or organization configuration.
`requestId`	AWS request identifier when safely available.
`error`	Stable code, redacted message, HTTP status, and retryability.

Finding results include a bounded set of ARN, account, title, description, severity, status, finding type, Inspector score, fix and exploit availability, observation times, and affected-resource identity. Coverage results include account, resource, resource type, scan mode, scan type, last-scan time, and scan status. Resource tags and provider-specific nested payloads are intentionally omitted.

IntegrationAccount Requirements

Use an AWS IntegrationAccount with:

status: READY
verified: true
access key ID in the account API-key field
secret access key in the protected password field

The connector never reads credentials from workflow input. It creates a regional AWS SDK client only after account verification and disables SDK-level retries so ValkyrAI can report exact attempt counts.

A deployment may need only the actions its reviewed workflows call:

inspector2:BatchGetAccountStatus
inspector2:ListFindings
inspector2:BatchGetFindingDetails
inspector2:ListCoverage
inspector2:ListCoverageStatistics
inspector2:ListMembers
inspector2:GetMember
inspector2:DescribeOrganizationConfiguration

Do not grant enable, disable, organization administration, member administration, suppression-filter mutation, deep-inspection mutation, or wildcard Inspector access merely to satisfy this connector.

Configuration

ExecModuleConfig supplies the IntegrationAccount and optional retry policy. All operations are reads. They retry transient throttling, server, and network failures up to the configured maximum, bounded from one to five attempts. The default is three.

The AWS SDK retry policy is disabled inside the connector. That keeps ValkyrAI's attempts field authoritative and avoids hidden replay behavior.

Operations

Finding prioritization

list_findings — return bounded, normalized findings with optional status, severity, and resource-type filters.
batch_get_finding_details — return focused risk enrichment for one to 10 exact finding ARNs, plus bounded per-finding errors.

A practical workflow can list active critical and high findings, deduplicate by ARN and update time, enrich a selected batch, assign the owning team from an approved inventory source, open or update remediation work, and wait for verified closure evidence. Inspector findings identify risk that deserves investigation; they do not by themselves prove exploitation, customer impact, or successful remediation.

Coverage and activation posture

batch_get_account_status — inspect Inspector activation and EC2, ECR, Lambda, and Lambda-code state for one to 100 exact accounts.
list_coverage — inspect bounded resource-level scan coverage and status.
list_coverage_statistics — group coverage counts by scan status, account, resource type, or ECR repository.

These operations make coverage gaps actionable. A platform workflow can compare expected accounts with activation state, group uncovered resources by type, and create measurable follow-up work without changing Inspector configuration. Coverage indicates whether Inspector reports a scan relationship; it is not a guarantee that every package, runtime path, or newly created resource has already produced a complete finding set.

Multi-account governance

list_members — list bounded member-account relationship state while omitting emails.
get_member — inspect one exact member and its delegated-administrator relationship.
describe_organization_configuration — inspect EC2, ECR, Lambda, and Lambda-code auto-enable posture plus account-limit state.

These reads support governance evidence and rollout checks. They do not associate accounts, appoint an administrator, or alter auto-enable policy.

Errors and Failure Modes

Code	Meaning	Retry guidance
`VALIDATION_ERROR`	A required field, identifier, enum, or bound is invalid.	Correct input; no provider call was made.
`INTEGRATION_ACCOUNT_ERROR`	The account is missing, unverified, not `READY`, or incomplete.	Repair and verify the account.
`UNSUPPORTED_OPERATION`	The operation is outside this release.	Select one documented operation.
`AWS_INSPECTOR_HTTP_400`	Inspector rejected an input or regional state.	Correct the target; inspect the request ID.
`AWS_INSPECTOR_HTTP_403`	IAM denied the operation.	Add only the missing least-privilege action.
`AWS_INSPECTOR_HTTP_404`	The account, finding, or member was not found.	Confirm region and exact identifier.
`AWS_INSPECTOR_HTTP_429` / `500` / `502` / `503` / `504`	Throttling or transient provider pressure.	Bounded read retries are automatic.
`NETWORK_ERROR`	ValkyrAI could not reach Inspector.	Verify connectivity and retry the read.
`EXECUTION_ERROR`	An unexpected local failure was safely contained.	Inspect server logs; secrets remain redacted.

Provider exception text is never returned to workflow output. AWS request IDs are preserved when safely available for CloudTrail and support correlation.

Example

List active critical and high findings affecting EC2 or Lambda:

{
  "operation": "list_findings",
  "region": "us-west-2",
  "findingStatuses": ["ACTIVE"],
  "severities": ["CRITICAL", "HIGH"],
  "resourceTypes": ["AWS_EC2_INSTANCE", "AWS_LAMBDA_FUNCTION"],
  "returnAll": true,
  "limit": 250
}

Expected result shape:

{
  "status": "success",
  "operation": "list_findings",
  "attempts": 1,
  "resultType": "findings",
  "items": [{
    "findingArn": "arn:aws:inspector2:us-west-2:123456789012:finding/example",
    "accountId": "123456789012",
    "severity": "CRITICAL",
    "status": "ACTIVE",
    "fixAvailable": "YES",
    "resources": [{"id": "i-example", "type": "AWS_EC2_INSTANCE", "region": "us-west-2"}]
  }],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "example-request-id"
}

Pass exact selected ARNs to batch_get_finding_details when a remediation workflow needs risk score, EPSS, CWE, reference, tool, or technique context. Keep provider findings and internal ownership evidence separate so each can be updated independently.

Notes

Pagination: Opaque Inspector tokens are preserved. returnAll follows no more than 100 pages and never returns more than 1,000 items.
Rate limits: All operations are reads and retry transient failures with bounded backoff and at most five configured attempts.
API limits: Account status accepts at most 100 unique account IDs. Finding detail accepts at most 10 unique finding ARNs.
Idempotency: Every supported operation is read-only and repeatable; no operation mutates AWS state.
Regional scope: Findings, coverage, activation, members, and organization results are requested through one exact regional endpoint. Endpoint overrides are not accepted.
Data minimization: Resource tags, raw evidence objects, nested package or code details, raw SDK payloads, and provider exception text are excluded.
Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production account and reviewed Inspector resources are supplied.
Deferred capabilities: Enable/disable, member association, organization update, suppression-filter mutation, deep-inspection mutation, and finding export are intentionally deferred.
Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsInspectorModule through /v1/modules/metadata.

Overview​

Usage​

Inputs​

Outputs​

IntegrationAccount Requirements​

Configuration​

Operations​

Finding prioritization​

Coverage and activation posture​

Multi-account governance​

Errors and Failure Modes​

Example​

Notes​

Related resources​