Guides & Downloads¶
Reference guides and downloads for AI SIEM. These are versioned — the links below point at the current release (26h4d) published on perfware.cloud.
Guides¶
- Getting Started Guide — deploy and configure the stack step by step.
- User Guide (PDF) — editor UI, threat management, response workflows.
- SSO Guide (PDF) — Okta, Azure AD, and SAML configuration.
Downloads¶
- Helper scripts (aisiem-scripts.zip) — helper scripts for AI SIEM.
AI SIEM Helper Scripts¶
Version 26h4d · 2026-11-10
Windows .cmd and Linux/macOS .sh versions are provided for most tasks; a few
run directly in Python and need boto3 (pip install boto3). Run each with AWS
credentials for the account named in its row of the script reference.
Every script prints its own usage when run with no arguments.
Commands below are written
scripts\name.cmdfor clarity. On Linux/macOS use the matchingscripts/name.sh(same arguments). If you run them from inside the unzipped bundle folder, drop thescripts\prefix.
Connecting data sources (start here)¶
AI SIEM takes data three different ways. Knowing which applies tells you whether there is anything to wire.
1. S3 log buckets — CloudTrail, VPC Flow Logs¶
Delivered as files to an S3 bucket. AI SIEM does not poll; the bucket must send
s3:ObjectCreated notifications to the ingestion queue.
- CloudTrail — enter the bucket in the editor (Configure → Data Sources). The
editor wires the notification for you when it can. If it reports it could not
(usually a cross-account bucket), use
wire-log-bucket. - VPC Flow Logs — the stack already owns the flow-log bucket (policy,
notification, Glue table). Run
create-flowlogsto turn on flow logs for a workload VPC you name, delivered to that stack bucket.
2. AWS-native events — GuardDuty, Security Hub, AWS Config¶
Arrive over EventBridge via rules the stack already created. In the SIEM's own
account nothing is wired. They only produce data when the underlying AWS service
is enabled and something happens, so zero events on a quiet account is normal.
AWS Config is off in a new account; turn it on with enable-config
— Security Hub depends on it.
- Cross-account — EventBridge findings do not cross accounts on their own.
To bring another account's findings in, run
wire-eventsin that account. The central stack must also have been deployed withOrganizationIdorCrossAccountIdsso its event bus accepts them.
3. Platform correlation — AI Monitor, Log Processor¶
AI Monitor writes metric anomalies into the shared OpenSearch domain; AI SIEM reads them and correlates. Log Processor pattern detections reach the SIEM the same way, through AI Monitor. There is no bucket and no script for this: in the editor (Configure → Data Sources → AI Monitor Correlation) pick which subscriptions contribute. That is the whole setup.
Case (1) always needs a helper for cross-account, and case (2) needs one only for cross-account EventBridge findings. Same-account (2) and all of (3) are wiring-free.
Cross-account log buckets (read this before wiring one)¶
A log bucket in another account (a common setup: an organization CloudTrail in a log-archive account) needs four things. Getting only some of them produces a silent failure that is easy to misread as "it works":
| # | Requirement | Who applies it |
|---|---|---|
| 1 | Notification — bucket sends s3:ObjectCreated to the ingestion queue |
wire-log-bucket |
| 2 | Queue policy — ingestion queue allows the bucket's account to send | wire-log-bucket |
| 3 | Bucket policy — allow <stack>-IngestionRole to s3:GetObject on the objects |
the bucket's owner |
| 4 | KMS key policy (only if the bucket is SSE-KMS encrypted) — allow that same IngestionRole to kms:Decrypt |
the bucket's owner |
Run wire-log-bucket with the profile of the account that owns the bucket:
scripts\wire-log-bucket.cmd AISIEM org-trail-logs us-east-1 logarchive
wire-log-bucket does 1 and 2. It does not do 3 and 4 — those must be
applied by the bucket's owner. Without 3 and 4, notifications still arrive and then
every object read fails: the queue drains into the DLQ and nothing is indexed, even
though the source shows as enabled. If a cross-account source looks connected but no
events appear, this is almost always why.
Alternative to 3 and 4: replicate the bucket into one the SIEM account owns and wire that.
Same-account buckets need only step 1 (the editor or wire-log-bucket handles it);
the queue policy already covers same-account, and no bucket/KMS grant is needed.
CloudTrail on a shared bucket: an organization CloudTrail already delivers every
member account to one bucket under AWSLogs/<account-id>/CloudTrail/..., which
ingestion tags per record — so one wire-log-bucket call (prefix AWSLogs/) covers
the whole org. If the same bucket also carries flow logs, wire each source on its
own non-overlapping prefix (see Prefixes on a shared bucket).
Cross-account EventBridge findings (GuardDuty, Security Hub, Config)¶
GuardDuty, Security Hub, and Config deliver findings to EventBridge only in the account and region where the service runs. The stack's own rules therefore see findings from the SIEM account only. To bring in another account's findings, forward them to the SIEM's event bus.
Central (SIEM) side — one-time, at deploy: deploy the stack with OrganizationId
(any account in the org may forward) or CrossAccountIds (only the listed
accounts may forward). This emits the bus policy that permits events:PutEvents onto
the SIEM's default event bus. The policy is source-agnostic, so it covers all three
sources at once. Setting neither leaves the bus closed — single-account
deployments need nothing.
Source side — run wire-events in the source account:
scripts\wire-events.cmd setup <central-account-id> [region] [--source LIST]
scripts\wire-events.cmd remove [region] [--source LIST]
scripts\wire-events.cmd status [region] [--source LIST]
--source is a comma list of guardduty,securityhub,config (default: all). setup
creates one forwarder role EventBridge assumes and one rule per source, sending
findings to the central account's default bus. Forwarded events keep their source and
originating accountId, which ingestion partitions on.
Where to run it (per source — you may not need it in every account)¶
| Source | Where to run |
|---|---|
| GuardDuty | Each source account + region. Exception: if a source account is your org's GuardDuty delegated administrator and the SIEM runs in it, member findings already aggregate there — wire-events detects central == local and no-ops. |
| Security Hub | If you use Security Hub finding aggregation, run it once in the aggregator account (it already holds every account's findings). If the SIEM is the aggregator, do nothing. Without aggregation, run per source account. |
| Config | Each source account + region. Forwards Config rule compliance changes only, so the account must have Config rules that evaluate. Full configuration snapshots (an S3 dataset) are not ingested today. |
AWS Config (optional, needed for compliance posture)¶
AWS Config is off in a new AWS account. It matters to AI SIEM in two ways:
- AI SIEM's Config source receives AWS Config rule compliance changes, so the account needs a recorder and at least one Config rule. A recorder alone sends nothing.
- Security Hub evaluates most of its controls through AWS Config. With Config off, Security Hub can check very little and its own control Config.1 fails (critical). That also thins out AI SIEM's Compliance Posture view, which is built on those findings.
enable-config turns recording on in the account and Region you run it in:
scripts\enable-config.cmd setup full us-east-1 --dry-run preview, writes nothing
scripts\enable-config.cmd setup full us-east-1 apply (asks to confirm)
scripts\enable-config.cmd status us-east-1 what is recorded; can Config.1 pass?
scripts\enable-config.cmd stop us-east-1 stop recording (and its charges)
| Mode | Records | Security Hub Config.1 | When to use |
|---|---|---|---|
minimal |
S3 buckets, IAM users / roles / policies, plus one managed rule | still fails | You only want AI SIEM's Config source, at the lowest cost. |
full |
All resource types. Network interfaces are recorded daily instead of on every change; rule results (AWS::Config::ResourceCompliance) stay continuous, since AWS does not support daily recording for them. |
passes | You use Security Hub or the Compliance Posture view. Recommended. |
Cost. AWS Config bills per configuration item recorded and per rule evaluation, per Region (AWS Config pricing).
- Day one costs the most. When recording starts, Config records one item for every existing resource of the recorded types (about $0.003 each), plus a result for each resource every Config rule evaluates. For example, an account with ~1,200 resources and rule results pays about $4 that first day.
- After that you pay only for changes, which is typically cents a day on a quiet account.
The inventory is charged again only if you delete the recorder and run
setupagain, or start recording new resource types (for example, switching fromminimaltofull).
After day one, what drives the bill is how often resources change, not how many exist. Network interfaces (which churn as
VPC Lambdas scale) and rule results are the usual surprises. full records network interfaces
daily; rule results grow with the number of Config rules (Security Hub standards add many), and
AWS records them on every change. A small account is typically a few dollars to a few tens of dollars a month. Check
Cost Explorer after 24–48 hours; stop halts recording and its charges without deleting the
recorder, rules or history. Once Config is recording, Security Hub's control checks (billed by
Security Hub) start running too.
The script is idempotent: an existing recorder and delivery channel are reused (AWS allows one
customer-managed recorder per Region), an existing bucket policy is merged, and re-running is
harmless. Flags: --profile P, --bucket NAME (default aisiem-config-<account>-<region>),
--no-global (when enabling a second Region, so global IAM items are not recorded and
billed twice), --no-rule, --yes, --dry-run.
Config is regional: run it in each Region you want covered. For other accounts, run it in
each account and forward their findings with wire-events
(--source config).
Multi-account setup¶
The multi-account model uses cross-account IAM roles for read access to CloudTrail and VPC Flow Log S3 buckets in remote accounts, plus an optional response role for enterprise-tier remediation. Advanced or Enterprise tier required.
- Remote account — create the trust roles:
scripts\setup-remote-access.cmd setup <central-account-id> [region] [--org <org-id>]
Creates AISIEM-remote-read and AISIEM-remote-respond. Pass --org <org-id>
to also trust any account in that AWS Organization.
- Central account — register the account so ingestion starts reading from it:
scripts\add-account.cmd <stack> <remote-account-id> --trail-bucket <bucket>
- Ingestion Lambda assumes
AISIEM-remote-readto list/read S3 objects. - Response Lambda assumes
AISIEM-remote-respondfor remediation (enterprise).
You can also list account IDs in the CrossAccountIds stack parameter, or set
OrganizationId to authorize an entire AWS Organization. Either may be used, or both.
Multi-region coverage¶
- CloudTrail — an organization trail delivers all regions to one bucket, so a single bucket covers everything.
- VPC Flow Logs — regional. Configure flow logs in each region to deliver to one central bucket.
- GuardDuty / Security Hub — EventBridge is regional and per-account. Use a
delegated administrator with auto-enable across regions (findings aggregate to the
admin account), or forward with
wire-eventsper source account + region.
VPC Flow Logs¶
VPC Flow Logs are the signal for network-based detections: port scanning, blocked
connections, and (with ALL traffic) large-transfer exfiltration. They are not on by
default because they bill per GB delivered and stored.
The stack already owns the flow-log bucket — when you deploy AI SIEM it creates a
hardened bucket (lifecycle, encryption, the delivery policy for local and
cross-account VPCs, the notification to the ingestion queue, and the Athena Glue table
flowlogs_raw over it). create-flowlogs does not create or wire a bucket; it
turns on a flow log for a VPC you name, pointed at that stack bucket, with per-hour
Hive partitioning so Athena can query it directly:
set AWS_PROFILE=<your-profile>
scripts\create-flowlogs.cmd <stack> --vpc <vpc-id>
scripts\create-flowlogs.cmd <stack> --vpc-from-stack <other-stack> --traffic REJECT
Re-running is harmless (every step is idempotent). Flow-log delivery is aggregated, so the first objects can take up to ~10 minutes to appear.
| Option | Meaning |
|---|---|
--vpc <id> / --vpc-from-stack <name> |
Required. Name the workload VPC to monitor, by id or by another stack's VpcId output. There is no default: this tool never enables flow logs on the shared LogProcessor / AI Monitor VPC the SIEM runs in (that would be a self-surveillance loop), and refuses to run if the target resolves to it. |
--traffic ALL\|REJECT\|ACCEPT |
ALL (default). S3 delivery is cheap even at ALL volume, and capturing everything is what lets the on-demand Athena flow-query pull exfiltration detail around an incident. Use REJECT only to minimize S3 storage (you then lose ALL-traffic forensics; port-scan detection still works). |
--bucket <name> |
Override the destination bucket. Defaults to the stack's FlowLogsBucket output; the main use is cross-account (run from a remote account and pass the central stack's bucket). |
--region <region> |
Default us-east-1. |
--profile <name> |
AWS profile. |
--dry-run |
Preview every change without writing. |
One or many VPCs, one bucket¶
Point as many VPCs as you like (any account, any region) at the one stack bucket. AWS
partitions deliveries under a Hive key path
(AWSLogs/aws-account-id=<id>/aws-service=vpcflowlogs/aws-region=<region>/year=/month=/day=/hour=/...),
so they never collide and the flowlogs_raw Glue table's partition projection resolves
them all. Run create-flowlogs once per VPC.
Cross-account flow-log delivery (honors CrossAccountIds / OrganizationId)¶
The stack bucket's policy already authorizes cross-account delivery, set at deploy time from the central stack's own parameters — there is no bucket policy for this helper to edit:
OrganizationIdset → the whole org may deliver (aws:SourceOrgID). No account list to maintain.CrossAccountIdsset → each listed account may deliver.
To onboard a remote VPC: run create-flowlogs from that account (with its own
credentials, since a flow log is created where the VPC lives) and pass
--bucket <central stack's FlowLogsBucket>. If the account is not covered by
OrganizationId / CrossAccountIds, redeploy the central stack with it added first.
Prefixes on a shared bucket¶
wire-log-bucket keys each notification by prefix, so one bucket can carry several
sources (e.g. cloudtrail/ and vpcflowlogs/) with distinct, coexisting notifications
— wiring a second prefix does not overwrite the first. Wire each with its own
--prefix. One caveat from S3: notification prefix filters for the same event type may
not overlap. Do not wire both a parent prefix (AWSLogs/) and a child
(AWSLogs/111/) on one bucket; use non-overlapping prefixes.
Audit trail (WORM audit bucket)¶
Every threat status change (acknowledge, investigate, resolve, false positive, dismiss) and every remediation action is recorded with who did it and when, in two places:
- DynamoDB — the fast path the editor reads to show "Audit History" per threat.
- A dedicated S3 bucket
<stack>-siem-audit-<acct>-<region>with S3 Object Lock (WORM), as the tamper-evident system of record. Each record is a write-once object: the application roles can append audit records but have no permission to alter or delete them, so even a compromised Lambda cannot rewrite history.
The lock behavior is chosen at deploy time with the AuditLockMode parameter:
- GOVERNANCE (default) — write-once, but a principal explicitly holding
s3:BypassGovernanceRetention(typically an account admin) can still delete a record early. This leaves a controlled decommission path. Recommended for most deployments. - COMPLIANCE — fully immutable. No one — not the application, not an admin, not the account root — can alter or delete a record before its retention date elapses. This is what strict regimes (e.g. SEC 17a-4-style requirements) need.
Consequence of COMPLIANCE mode: an S3 bucket can only be deleted when empty, and COMPLIANCE-locked objects cannot be emptied until their retention passes. So under COMPLIANCE the audit bucket — and its storage cost — cannot be removed until the last record's retention has elapsed. Because this makes
AuditRetentionDaysan irreversible commitment, set it to your actual regulatory requirement, not higher "to be safe." Under GOVERNANCE an over-long retention is recoverable via bypass; under COMPLIANCE it is not.
Retention length: AuditRetentionDays (default 365; e.g. 2555 for 7 years). Applies
to newly written records; existing records keep the mode and retention they were written
under. The audit bucket has DeletionPolicy: Retain — a stack delete leaves it in place
(it is the system of record and must outlive the stack).
Teardown (removing AI SIEM)¶
Deleting the stack does not stop your log sources. Bucket notifications and any VPC flow logs created for AI SIEM live outside CloudFormation and survive the delete. Left in place, buckets keep firing notifications at a queue that no longer exists, and flow logs keep writing to S3 while you keep paying for it. Run in this order:
1. Preview what is attached (dry run — changes nothing):
python scripts\sever_sources.py <stack> [region]
Reports VPC flow logs delivering to S3, bucket notifications owned by this stack, the CloudTrail trail and whether it is still logging, and Lambda reserved concurrency (reported, never changed). Read this before going further.
2. Detach the sources:
python scripts\sever_sources.py <stack> [region] --apply
Confirms each item individually. Deletes the flow logs, removes this stack's bucket notifications (merge-safe — only Ids belonging to this stack are dropped; anything another tool put there is written back untouched), and stops the trail.
| Flag | Effect |
|---|---|
--delete-trail |
Delete the trail instead of stopping it. A multi-region trail is an audit control and deleting it breaks CloudTrail history continuity for the whole account, so stopping is the default. |
--bucket-profile <name> |
For buckets in another account. Use the same profile you passed to wire_log_bucket.py, once per account. |
--delete-buckets |
Irreversible. Also empty and delete the log buckets AI SIEM created. Deliberately narrow: a bucket qualifies only if its name starts with aisiem-cloudtrail-, or it is the destination of a flow log or trail found in step 1. The stack-owned flow-log bucket is never a candidate (CloudFormation deletes it with the stack). A bucket that merely carries one of our notifications — most likely your archive — is never deleted. Each bucket prints its version/delete-marker count and size, then requires you to type the name back before anything is destroyed. |
3. Delete the CloudFormation stack:
aws cloudformation delete-stack --stack-name <stack> --region <region>
aws cloudformation wait stack-delete-complete --stack-name <stack> --region <region>
Buckets with content and any resource still in use can hold the delete up; the stack events tab names whatever is blocking.
4. Sweep up orphans the stack delete left behind:
python scripts\cleanup.py <stack> <region>
Removes what CloudFormation could not: buckets that still held content, the interface VPC endpoints and SIEM Lambda security group (both live in the shared VPC but are owned by this stack), ENIs still detaching, and named resources (Lambdas, queues, topics, alarms, rules, ALB, Cognito pool, dashboard) matched by this stack's name prefix. Dry run by default — it only reports until you add a flag. Safe to re-run.
VPC-safe: AI SIEM is a guest in the shared Log Processor VPC alongside AI Monitor.
cleanupnever deletes the VPC, subnets, gateways, or the OpenSearch domain, and identifies in-VPC resources strictly by this stack's CloudFormation tag / name prefix, so Log Processor's and AI Monitor's endpoints and security groups are never candidates.
| Flag | Effect |
|---|---|
-force |
Delete everything it found without prompting. |
-confirm |
Prompt before each deletion. |
-delete-buckets |
Irreversible. Also empty and delete the log/threat archive buckets (never the WORM audit bucket). Off by default; a routine cleanup only reports them. |
-delete-audit |
Irreversible. Also remove the WORM audit bucket, bypassing Object Lock retention — a separate, deliberate decommission (see Audit trail). |
-delete-kms |
Irreversible. Schedule deletion of the Bedrock-privacy token-map KMS key (alias/<stack>-token-map). After this, any still-cached redacted playbook can no longer be de-tokenized (it falls back to showing tokens — fail-safe, not a crash). |
5. OpenSearch artifacts — no action needed. The stack's custom resources remove AI SIEM's dashboards, index templates, ISM policy, and seed indices from the shared domain automatically on delete. (Your event data lives in the S3 datalake, not the domain.)
Things no script does — decide deliberately¶
- Log buckets you wired in yourself are never deleted; verify with
aws s3 lsthat what you expect to keep is still there. - Cross-account roles created by
setup-remote-access(AISIEM-remote-read,AISIEM-remote-respond) remain in each remote account. Remove them there withsetup-remote-access.cmd remove <central-account-id>. - Source-account forwarding set up with
wire-events(theAISIEM-*-forwardrules +AISIEM-eventbridge-forward-role) lives in those remote accounts and survives — remove it withwire-events.cmd remove [region]in each. - The WORM audit bucket (
<stack>-siem-audit-*) always survives the stack delete (DeletionPolicy: Retain). Decommissioning it is a separate, deliberate step — under COMPLIANCE it cannot be removed until every record's retention has elapsed. See Audit trail. - The delegated remediation add-on, if deployed, created a separate
aisiem-remediation-<stack>stack in each account where remediations execute. Tear it down per account withscripts\remediation_docs\deploy-remediation.cmd <stack> --cleanup— seeremediation_docs/README.md.
Querying historical data¶
Every event is written to an S3 datalake in Parquet, partitioned by account_id and
region for efficient Athena queries and per-account lifecycle, regardless of whether it
was promoted to OpenSearch:
s3://<stack>-siem-datalake-<acct>-<region>/
cloudtrail/account_id=.../region=.../year=.../month=.../day=.../*.parquet
flowlogs/account_id=.../region=.../year=.../month=.../day=.../*.parquet
guardduty/ securityhub/ config-changes/ threats/
A Glue database named <stack>_siem is created with tables over these prefixes. Filter on
the partition columns so Athena scans only what it needs:
SELECT * FROM cloudtrail
WHERE account_id = '111111111111'
AND region = 'us-east-1'
AND year = '2026' AND month = '08';
Script reference¶
| Script | Run in | Purpose |
|---|---|---|
check-quota.cmd / check_quota.py |
AI SIEM account | Verify service quotas before deploying (Lambda concurrency, per-VPC interface-endpoint headroom). |
setup-domain.cmd / .sh |
AI SIEM account | Editor custom domain. cert-only issues + validates the ACM certificate before launch; <stack> mode creates the Route 53 alias to the ALB after deploy. |
create-flowlogs.cmd / .sh / create_flowlogs.py |
AI SIEM account | Enable VPC Flow Logs on a workload VPC, delivered to the stack-owned flow bucket. Requires a target VPC; never touches the shared VPC. |
wire-log-bucket.cmd / .sh / wire_log_bucket.py |
Either | Attach a log bucket (CloudTrail or Flow Logs) to the ingestion queue when the editor cannot — notification + queue policy (merge-safe). Supports --prefix for shared buckets. |
setup-remote-access.cmd / .sh |
Remote account | Create the cross-account trust roles (setup / remove / status; --org). |
add-account.cmd / .sh |
AI SIEM account | Register a remote account and its buckets (<id> / list / remove). |
wire-events.cmd / .sh |
Source account | Forward a source account's GuardDuty / Security Hub / Config findings to the central event bus (setup / remove / status, --source LIST). |
enable-config.cmd / .sh / enable_config.py |
Each account + Region to cover | Turn on AWS Config recording: setup minimal\|full, status (can Security Hub Config.1 pass?), stop (halts recording and its charges). full records all types, with network interfaces daily. See AWS Config. |
users.cmd / .sh |
AI SIEM account | Cognito users: create, list, delete, reset password, enable/disable. |
groups.cmd / .sh |
AI SIEM account | Cognito groups for role-based access: init, add/remove, list (enterprise tier). |
sso.cmd / .sh |
AI SIEM account | Configure SAML or OIDC identity providers (enterprise tier). |
support-bundle.cmd / .sh / support_bundle.py |
AI SIEM account | Collect diagnostics into a timestamped folder for support (CFN stack/resources/events, per-Lambda config, SQS depth/age + DLQs, alarm states, custom metric counts, DynamoDB + baseline maturity, SNS subs, enabled sources, paired Log Processor status). support-bundle.cmd <stack> [hours] [--no-logs]. By default also captures recent ERROR/WARNING log lines, which can contain identifiers — review/redact the lambda-*-errors/-warnings.json before sending, or pass --no-logs to skip log capture. Zip the folder (command printed) and email it; analyze with dev/analyze-bundle.py. |
sever_sources.py |
AI SIEM account | Detach log sources — the inverse of wire_log_bucket. First teardown step. |
cleanup.py |
AI SIEM account | Sweep up orphan resources a stack delete leaves behind (buckets with content, this stack's VPC endpoints / Lambda SG, detaching ENIs, prefix-matched named resources). VPC-safe; dry-run by default. Final teardown step, after the stack delete. -force / -confirm / -delete-buckets / -delete-audit / -delete-kms. |
remediation_docs/ |
Account where remediations execute | Self-contained bundle for delegated auto-remediation (add-on template, sample runbooks, deploy helpers). Read remediation_docs/README.md first. |
Delegated remediation (remediation_docs/)¶
A self-contained subfolder for delegated auto-remediation, with its own README.md
(read it before running these). Run in the account where remediations execute:
deploy-remediation.cmd/.sh <siem-stack>— creates theAutomationAssumeRoleSSM Automation assumes to run your runbooks (you scope its permissions) and publishes its ARN to SSM so the editor auto-fills it. Teardown: same command with--cleanup.deploy-sample-runbooks.cmd/.sh [region] [--privileged]— creates the no-op test runbooks (AISIEM-Ping,AISIEM-TestRemediation);--privilegedalso adds the isolate / attach-deny samples.
AI SIEM only calls ssm:StartAutomationExecution and reads status — it holds no IAM/EC2
power; SSM runs everything under your role.