AI Monitor - Operational Scripts
=================================

All scripts are available as .cmd (Windows) and .sh (Linux/macOS).
AWS CLI must be configured with appropriate credentials before use.


users.cmd / users.sh
--------------------
Manage Cognito users for the AI Monitor editor.

Usage:
  users.cmd <stack-name> <action> [email] [temp-password] [region]

Actions:
  create <email> [temp-password]   Create a new user (prompted to reset on first login)
  list                             List all users
  delete <email>                   Delete a user
  reset <email> [temp-password]    Reset password (temporary, must change on login)
  disable <email>                  Disable a user
  enable <email>                   Re-enable a user

Examples:
  users.cmd AIMonitor create admin@example.com "Temp*88=888Pass123!@#"
  users.cmd AIMonitor list
  users.cmd AIMonitor disable user@example.com


groups.cmd / groups.sh
----------------------
Manage Cognito groups for RBAC (advanced+ tiers).
Users in the "admin" group have full access. Users in the "viewer" group are read-only.
Users not in any group are denied access.

Usage:
  groups.cmd <stack-name> <command> [args] [region]

Commands:
  list-groups                         List all groups
  create-group <name> [description]   Create a new group
  delete-group <name>                 Delete a group
  add-to-group <user> <group>         Add a user to a group
  remove-from-group <user> <group>    Remove a user from a group
  list-users [group]                  List users (optionally in a specific group)

Examples:
  groups.cmd AIMonitor create-group admin "Full access editors"
  groups.cmd AIMonitor create-group viewer "Read-only access"
  groups.cmd AIMonitor add-to-group admin@example.com admin
  groups.cmd AIMonitor list-users admin

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).
    
support-bundle.cmd / support-bundle.sh
--------------------------------------
Collects diagnostic information for troubleshooting. Outputs a timestamped
bundle directory with Lambda configs, recent logs, DynamoDB state, CloudWatch
metrics, alarm status, discovery cache, AI circuit breaker state, and more.

Usage:
  support-bundle.cmd <stack-name> [region]

Output:
  support-bundle-<timestamp>/ directory with JSON/text files.
  Run analyze-bundle.py on the output for a summary report.

Examples:
  support-bundle.cmd AIMonitor
  python analyze-bundle.py support-bundle-20250115-143022/


setup-cross-account-metrics.cmd / setup-cross-account-metrics.sh
-----------------------------------------------------------------
Run in the REMOTE account to set up cross-account metric delivery into the
central AI Monitor stack's S3 bucket.

Architecture:
  Remote: Metric Stream -> Firehose (+ transform Lambda) -> Central S3
  Central: S3 event -> SQS -> Collector Lambda -> OpenSearch

CloudWatch Metric Streams require Firehose in the SAME account.
Firehose supports cross-account S3 destinations natively.

Prerequisites:
  - Central AI Monitor stack deployed with CrossAccountIds including the remote account
  - AWS CLI configured for the REMOTE account

Usage:
  setup-cross-account-metrics.cmd <central-account-id> <central-stack-name> <central-region>

Example:
  setup-cross-account-metrics.cmd 765710438805 AIMonitor us-east-1

Creates in the remote account:
  1. Transform Lambda (splits Metric Stream concatenated JSON)
  2. Firehose delivery stream with Lambda processor + cross-account S3 destination
  3. CloudWatch Metric Stream -> local Firehose

To filter namespaces after setup:
  aws cloudwatch put-metric-stream --name AIMonitor-remote-stream \
    --firehose-arn arn:aws:firehose:... --role-arn arn:aws:iam:... \
    --output-format json --include-filters Namespace=AWS/Lambda Namespace=AWS/EC2


Enabling AWS/Billing Metrics in Remote Accounts
------------------------------------------------
AWS/Billing metrics (EstimatedCharges) are not enabled by default.
Each account that needs billing monitoring must enable this separately.

Steps:
  1. Log in to the AWS Management Console as the root user or an IAM identity
     with billing permissions.
  2. Navigate to the AWS Billing and Cost Management console.
  3. In the left navigation pane, choose Billing preferences.
  4. Find the "Alert preferences" section and choose Edit.
  5. Select the checkbox for "Receive CloudWatch Billing Alerts".
  6. Choose Save preferences (or Update) to apply the changes.

Note: Billing metrics are only published in us-east-1 regardless of which
region your resources are in. The Metric Stream in the remote account must
be in us-east-1, or you must create a separate stream in us-east-1 for
AWS/Billing if your primary stream is in another region.

After enabling, AWS/Billing EstimatedCharges metrics will begin publishing
within a few hours. These can then be streamed cross-account like any other
CloudWatch metric.
