LogProcessor Helper Scripts 26h1
===========================

Prerequisites
-------------
- Windows 10/11 or Windows Server 2016+
- AWS CLI v2.13+ (latest recommended): https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
- AWS credentials configured (aws configure, SSO, or environment variables)
- PowerShell 5.1+ (included with Windows 10/11)
- Python 3.10+ (only for cleanup.py)

All scripts should be run from the project root or any directory with
AWS CLI access to the target account and region.


Scripts
-------
users.cmd <stack-name> create <email> [temp-password] [region]
users.cmd <stack-name> list [region]
users.cmd <stack-name> delete <email> [region]
users.cmd <stack-name> reset <email> [temp-password] [region]
users.cmd <stack-name> disable <email> [region]
users.cmd <stack-name> enable <email> [region]
    Manage Cognito users for OpenSearch Dashboards and Subscription
    Editor access.
    - create:  Create a user with a temporary password (forced change on first login)
    - list:    List all users with status
    - delete:  Remove a user
    - reset:   Reset password (user must set new one on next login)
    - disable: Block a user from logging in
    - enable:  Re-enable a disabled user
    Requires: AWS CLI, Cognito UserPool deployed (essential+ tier).

users.sh <stack-name> create <email> [temp-password] [region]
users.sh <stack-name> list [region]
users.sh <stack-name> delete <email> [region]
users.sh <stack-name> reset <email> [temp-password] [region]
users.sh <stack-name> disable <email> [region]
users.sh <stack-name> enable <email> [region]
    Bash version of users.cmd for Linux, macOS, and Git Bash on Windows.
    Same functionality and arguments as users.cmd.
    Requires: bash, AWS CLI, Cognito UserPool deployed (essential+ tier).

groups.cmd <stack-name> list-groups [region]
groups.cmd <stack-name> create-group <name> [description] [region]
groups.cmd <stack-name> delete-group <name> [region]
groups.cmd <stack-name> add-to-group <user> <group> [region]
groups.cmd <stack-name> remove-from-group <user> <group> [region]
groups.cmd <stack-name> list-users [group] [region]
    Manage Cognito user groups for role-based access control.
    - list-groups:       List all groups in the user pool
    - create-group:      Create a new group (e.g. admin, viewer)
    - delete-group:      Remove a group
    - add-to-group:      Assign a user to a group
    - remove-from-group: Remove a user from a group
    - list-users:        List all users, or users in a specific group
    Editor RBAC (Advanced+ tier):
      Users in the "admin" group get full editor access.
      Users in any other group (e.g. "viewer") get read-only access.
      Users not in any group are blocked from the editor.
    Requires: AWS CLI, Cognito UserPool deployed (essential+ tier).

groups.sh <stack-name> list-groups [region]
groups.sh <stack-name> create-group <name> [description] [region]
groups.sh <stack-name> delete-group <name> [region]
groups.sh <stack-name> add-to-group <user> <group> [region]
groups.sh <stack-name> remove-from-group <user> <group> [region]
groups.sh <stack-name> list-users [group] [region]
    Bash version of groups.cmd for Linux, macOS, and Git Bash on Windows.
    Same functionality and arguments as groups.cmd.
    Requires: bash, AWS CLI, Cognito UserPool deployed (essential+ tier).

setup-domain.cmd cert-only <domain> <hosted-zone-id> [region]
setup-domain.cmd <stack-name> <domain> <hosted-zone-id> [region]
    Configure a custom domain for the Dashboards ALB.
    Use cert-only mode before deployment to request and validate an
    ACM certificate. After deployment, run with the stack name to
    create the Route 53 alias record pointing to the ALB.
    Requires: AWS CLI, Route 53 hosted zone.

setup-domain.sh cert-only <domain> <hosted-zone-id> [region]
setup-domain.sh <stack-name> <domain> <hosted-zone-id> [region]
    Bash version of setup-domain.cmd for Linux, macOS, and Git Bash on Windows.
    Same functionality and arguments as setup-domain.cmd.
    Requires: bash, AWS CLI, Route 53 hosted zone.

snapshot.cmd <stack-name> <action> [name] [region]
    Manage OpenSearch manual snapshots (take, list, status, delete).
    Actions: take <name>, list, status <name>, delete <name>
    Requires: AWS CLI, OpenSearch snapshot repository configured.

snapshot.sh <stack-name> <action> [name] [region]
    Bash version of snapshot.cmd for Linux, macOS, and Git Bash on Windows.
    Same functionality and arguments as snapshot.cmd.
    Requires: bash, AWS CLI, OpenSearch snapshot repository configured.

support-bundle.cmd <stack-name> [hours] [region]
    Collect a diagnostic bundle for support analysis.
    Gathers CloudFormation state, Lambda logs/config, SQS queue depth,
    OpenSearch domain status, CloudWatch metrics/alarms, SNS subscriptions,
    S3 bucket status, Firehose config, editor logs, ALB health, Nginx
    logs, and the current subscriptions.json.
    Output: support-bundle/<stack-name>-<timestamp>/ folder.
    Default: 24 hours of history. Zip the folder and email to support.
    Requires: AWS CLI, read access to stack resources.

support-bundle.sh <stack-name> [hours] [region]
    Bash version of support-bundle.cmd for Linux, macOS, and Git Bash on Windows.
    Same functionality and arguments as support-bundle.cmd.
    Requires: bash, AWS CLI, read access to stack resources.

get-destination.cmd <stack-name>
    Display the CloudWatch Logs destination ARN for a stack.
    Use this ARN when setting up cross-account log forwarding.
    Requires: AWS CLI, logs:DescribeDestinations permission.

get-destination.sh <stack-name> [region]
    Bash version of get-destination.cmd for Linux, macOS, and Git Bash on Windows.
    Same functionality and arguments as get-destination.cmd.
    Requires: bash, AWS CLI, logs:DescribeDestinations permission.

setup-cross-account.cmd setup <log-group> <destination-arn> [filter] [region]
setup-cross-account.cmd list [region]
setup-cross-account.cmd remove <log-group> [region]
    Manage cross-account log subscriptions. Run in the EXTERNAL account
    to forward CloudWatch logs to a LogProcessor destination.
    - setup:  Create a subscription filter on a log group
    - list:   List all cross-account subscription filters
    - remove: Remove the subscription filter from a log group
    Prerequisites (in the LogProcessor account):
      - Enterprise/Magnus tier deployed
      - This account's ID in the CrossAccountIds parameter
    Requires: AWS CLI, logs:PutSubscriptionFilter,
    logs:DeleteSubscriptionFilter, logs:DescribeSubscriptionFilters.

setup-cross-account.sh setup <log-group> <destination-arn> [filter] [region]
setup-cross-account.sh list [region]
setup-cross-account.sh remove <log-group> [region]
    Bash version of setup-cross-account.cmd for Linux, macOS, and Git Bash on Windows.
    Same functionality and arguments as setup-cross-account.cmd.
    Requires: bash, AWS CLI, same permissions as setup-cross-account.cmd.

cleanup.py <stack-name> [region]
    Clean up orphaned resources after stack deletion.
    Removes log groups, S3 buckets, and other resources that
    CloudFormation may leave behind with RETAIN policies.
    Requires: Python 3.10+, boto3, appropriate IAM permissions.

sso.cmd <stack-name> setup-saml <name> <metadata-url>
sso.cmd <stack-name> setup-oidc <name> <issuer> <client-id> <client-secret>
sso.cmd <stack-name> list
sso.cmd <stack-name> remove <name>
sso.cmd <stack-name> info
    Manage external SSO (SAML/OIDC) identity providers on the Cognito
    User Pool for federated login to Dashboards and Subscription Editor.
    - setup-saml: Add a SAML identity provider (Okta, ADFS, etc.)
    - setup-oidc: Add an OIDC identity provider (Azure AD, Google, etc.)
    - list:       List configured identity providers
    - remove:     Remove an identity provider
    - info:       Show ACS URL, Entity ID, and Redirect URI for IdP setup
    After adding an IdP, users see a "Sign in with <name>" button.
    Assign groups after first login: groups.cmd <stack> add-to-group <email> admin
    Requires: AWS CLI, Cognito UserPool deployed (essential+ tier).

sso.sh <stack-name> setup-saml <name> <metadata-url>
sso.sh <stack-name> setup-oidc <name> <issuer> <client-id> <client-secret>
sso.sh <stack-name> list
sso.sh <stack-name> remove <name>
sso.sh <stack-name> info
    Bash version of sso.cmd for Linux, macOS, and Git Bash on Windows.
    Same functionality and arguments as sso.cmd.
    Requires: bash, AWS CLI, Cognito UserPool deployed (essential+ tier).

add-access-logging.cmd <stack-name> list [region]
add-access-logging.cmd <stack-name> add <source-bucket> [region]
add-access-logging.cmd <stack-name> remove <source-bucket> [region]
    Enable, list, or remove S3 access logging on any bucket, targeting
    the stack's access log bucket with date-based partitioning under
    the access/ prefix.
    - list:   Show buckets that have delivered logs (may take up to
              1 hour after adding a new bucket)
    - add:    Enable access logging on a bucket
    - remove: Disable access logging (existing logs retained)
    Works with any source bucket encryption (SSE-S3, SSE-KMS, CMK).
    Logs are queryable via the Athena access_logs table:
      SELECT * FROM access_logs
      WHERE bucket = 'my-bucket' AND date = '2026/05/03'
    No additional IAM permissions needed for same-account buckets.
    Requires: AWS CLI, S3 permissions on both buckets.

add-access-logging.sh <stack-name> list [region]
add-access-logging.sh <stack-name> add <source-bucket> [region]
add-access-logging.sh <stack-name> remove <source-bucket> [region]
    Bash version of add-access-logging.cmd for Linux, macOS, and Git Bash on Windows.
    Same functionality and arguments as add-access-logging.cmd.
    Requires: bash, AWS CLI, S3 permissions on both buckets.

setup-replication.cmd setup <target-bucket> [region] [--expire-days N] [--noncurrent-days N]
setup-replication.cmd add <source-bucket> [region]
setup-replication.cmd verify <source-bucket> [region]
setup-replication.cmd remove [region]
    Cross-account S3 access log replication. Run in the EXTERNAL account
    to replicate access logs to a LogProcessor stack's access log bucket.
    - setup:  One-time: create shared log bucket (access-logs-<acct>-<region>),
              IAM replication role, and replication rule to the target
    - add:    Enable access logging on a source bucket, pointing to the
              shared log bucket. Repeat for each bucket to monitor.
    - verify: Check logging and replication status for a source bucket
    - remove: Remove replication config (keeps role/bucket for cleanup)
    Options (setup only):
      --expire-days N      Delete objects from local log bucket after N days
      --noncurrent-days N  Delete noncurrent versions after N days
    The target-bucket is the LogProcessor access log bucket, e.g.:
      logprocessor-access-logs-765710438805-us-east-1
    Prerequisites (in the LogProcessor account):
      - Enterprise/Magnus tier deployed
      - This account's ID in the CrossAccountIds parameter
    Logs use partitioned prefix format (EventTime) and are queryable
    via the Athena access_logs table:
      SELECT * FROM access_logs
      WHERE bucket = 'my-bucket' AND date = '2026/05/04'
    Requires: AWS CLI, IAM permissions (iam:CreateRole, iam:PutRolePolicy),
    S3 permissions on source and local log buckets.

setup-replication.sh setup <target-bucket> [region] [--expire-days N] [--noncurrent-days N]
setup-replication.sh add <source-bucket> [region]
setup-replication.sh verify <source-bucket> [region]
setup-replication.sh remove [region]
    Bash version of setup-replication.cmd for Linux, macOS, and Git Bash on Windows.
    Same functionality and arguments as setup-replication.cmd.
    Requires: bash, AWS CLI, same permissions as setup-replication.cmd.


Defaults
--------
- Region defaults to us-east-1 if not specified.
- Stack name is case-sensitive and must match the CloudFormation stack name.


Support
-------
Email support bundles to: support@perfware.cloud
Documentation: https://perfware.cloud
