Amazon Macie ExecModule

Overview

The Amazon Macie ExecModule turns sensitive-data discovery and S3 security posture into bounded, governed workflow data. Teams can prioritize classification and policy findings, retrieve exact finding details, measure sensitive-data risk across monitored buckets, inspect classification-job progress, and review regional Macie or member-account posture without placing AWS credentials in workflow payloads.

The connector is designed for privacy and security response, not for exporting sensitive objects. Finding details normalize the identity, category, severity, title, timestamps, and affected bucket fields that workflows need for triage. Bucket reads expose monitored inventory, access, encryption, size, and classification posture. The module intentionally omits sensitive-data occurrence details, S3 object keys, member email addresses, bucket tags, raw SDK payloads, and provider exception text.

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 identifiers, and duplicate list entries are rejected before any AWS request.

Usage

1. Enable Amazon Macie in each AWS region the workflow must inspect.
2. Create a least-privilege AWS identity containing only the Macie read actions the workflow needs.
3. Store its access-key pair in a ValkyrAI IntegrationAccount, verify it, and keep it in READY status.
4. Add AwsMacieModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Set the exact AWS region, choose one supported operation, and supply only that operation's filters or identifiers.
6. Use limit for a deliberate total bound. Enable returnAll only when the downstream workflow can safely process every page up to that bound.
7. Preserve finding IDs and updatedAt values when deduplicating triage or remediation work.

Amazon Macie is regional. A successful result in one region does not prove Macie is enabled, configured, or complete elsewhere. This release does not enable or disable Macie, create classification jobs, alter sensitive-data discovery, change member relationships, archive findings, or read S3 object contents.

Inputs

Input	Type	Required	Default	Description
operation	string	Yes	—	One supported Amazon Macie read operation.
region	string	Yes	—	Exact AWS region such as us-west-2.
nextToken	string	No	—	Opaque continuation token returned by Macie.
limit	integer	No	100	Total list bound from 1 to 1,000.
returnAll	boolean	No	false	Follow provider pages until limit or exhaustion.
findingIds	array	Finding detail	—	One to 50 unique Macie finding IDs.
severities	array	No	—	Any of LOW, MEDIUM, and HIGH.
categories	array	No	—	CLASSIFICATION, POLICY, or both.
includeArchived	boolean	No	false	Include archived findings in finding criteria.
bucketNames	array	Bucket inventory	—	Up to 50 unique exact S3 bucket names.
jobId	string	Job detail	—	One exact classification-job ID.
accountId	string	Bucket statistics	—	Optional exact 12-digit member account ID.
groupBy	string	Finding statistics	severity.description	Severity, finding type, job ID, or affected bucket name.
onlyAssociated	boolean	Member inventory	true	Limit member results 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 finding_ids, findings, buckets, or classification_jobs.
items / count	Bounded normalized list results and returned count.
pages / hasMore / nextToken	Pagination evidence for list operations.
data	Session, bucket-statistics, or classification-job detail.
requestId	AWS request identifier when safely available.
error	Stable code, redacted message, HTTP status, and retryability.

Finding detail includes bounded identity, account, category, severity, title, description, type, timestamps, and affected bucket context. Bucket inventory includes access, upload-encryption requirement, automated discovery monitoring, size, object counts, sensitivity score, versioning, and safe error state. Classification-job detail contains status, timing, sampling, identifier counts, and high-level processing statistics without exporting matched data.

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:

macie2:GetMacieSession
macie2:ListFindings
macie2:GetFindings
macie2:GetFindingStatistics
macie2:DescribeBuckets
macie2:GetBucketStatistics
macie2:ListClassificationJobs
macie2:DescribeClassificationJob
macie2:ListMembers

Do not grant Macie administration, classification-job creation, member administration, finding mutation, S3 object reads, or wildcard 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. This keeps ValkyrAI's attempts field authoritative and avoids hidden replay behavior.

Operations

Sensitive-data finding triage

• list_findings — return bounded finding IDs filtered by severity, category, and archive state.
• get_findings — retrieve normalized detail for one to 50 exact finding IDs.
• get_finding_statistics — group filtered finding counts by severity, type, classification job, or affected bucket.

A practical workflow can list active high-severity classification findings, retrieve a reviewed batch of exact IDs, route each affected bucket to an approved owner, and open or update remediation work. Macie findings are evidence for investigation; they do not by themselves prove unauthorized access, regulatory impact, or successful remediation.

S3 security and classification posture

• describe_buckets — inspect bounded monitored-bucket inventory, optionally for exact bucket names.
• get_bucket_statistics — measure account-level bucket counts, effective permissions, encryption, shared access, upload requirements, classifiability, and sensitivity groups.

These reads help teams find publicly accessible buckets, unencrypted upload paths, monitoring gaps, and classification backlogs without reading object contents. Statistics describe Macie's current regional view; they are not a substitute for an authoritative asset inventory or a complete access review.

Classification operations

• list_classification_jobs — list bounded job identity, type, state, creation time, and safe error code.
• describe_classification_job — inspect one exact job's state, schedule characteristics, identifier counts, and processing statistics.

Workflows can detect jobs that have stopped progressing, compare expected and observed runs, and create follow-up work while keeping any discovered sensitive values outside the workflow result.

Account and organization posture

• get_macie_session — inspect regional service status, finding publication frequency, and lifecycle timestamps.
• list_members — list bounded member-account relationship state while omitting member email addresses.

These reads support regional activation and delegated-administration evidence. They do not enable Macie, invite accounts, or change organization relationships.

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_MACIE_HTTP_400	Macie rejected an input or regional state.	Correct the target; inspect the request ID.
AWS_MACIE_HTTP_403	IAM denied the operation.	Add only the missing least-privilege action.
AWS_MACIE_HTTP_404	The finding, job, bucket context, or account was not found.	Confirm region and exact identifier.
AWS_MACIE_HTTP_429 / 500 / 502 / 503 / 504	Throttling or transient provider pressure.	Bounded read retries are automatic.
NETWORK_ERROR	ValkyrAI could not reach Macie.	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

Build a bounded queue of high-severity classification findings:

{
  "operation": "list_findings",
  "region": "us-west-2",
  "severities": ["HIGH"],
  "categories": ["CLASSIFICATION"],
  "includeArchived": false,
  "returnAll": true,
  "limit": 250
}

Expected result shape:

{
  "status": "success",
  "operation": "list_findings",
  "attempts": 1,
  "resultType": "finding_ids",
  "items": [{"findingId": "example-finding-id"}],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "example-request-id"
}

Pass reviewed IDs to get_findings when a response workflow needs category, severity, affected bucket, and update-time context. Keep provider findings, internal ownership, and remediation evidence as separate records so each can be updated and audited independently.

Notes

• Pagination: Opaque Macie 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: Finding detail and exact bucket filters accept at most 50 unique identifiers per call.
• Idempotency: Every supported operation is read-only and repeatable; no operation mutates AWS or S3 state.
• Regional scope: Findings, buckets, jobs, session state, and members are requested through one exact regional endpoint. Endpoint overrides are not accepted.
• Data minimization: Sensitive-data occurrence details, S3 object keys, member emails, bucket tags, 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 Macie resources are supplied.
• Deferred capabilities: Macie enablement, automated-discovery changes, job creation, finding archival, member mutation, and S3 object access are intentionally deferred.
• Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsMacieModule through /v1/modules/metadata.

Related resources

• Amazon Macie API Reference
• Amazon Macie service authorization
• AWS Security Hub ExecModule
• Amazon GuardDuty ExecModule
• AWS S3 ExecModule