### [IDE Integrations](/integrations)
**Connect your IDE**: Deploy infrastructure from Cursor, VS Code, Claude Desktop, ChatGPT, or JetBrains with MCP integration.
### [Cookbooks](/cookbooks)
**Tutorials**: Step-by-step guides for deploying infrastructure, setting up CI/CD, and automating workflows.
### [User Guide](/guide)
**Platform Reference**: Explore workloads, security rules, governance, and the full CloudAgent dashboard.
### [LLM Docs](/llms.txt)
**For AI Agents**: Single-file documentation optimized for AI agents and LLMs.
> **Note:**
**New to CloudAgent?** Start with [Deploy AWS from Cursor](/cookbooks/deploy-aws-cursor) to ship your first infrastructure in 10 minutes.
# User Guide
# Introduction
# CloudAgent User Guide
Welcome to the User Guide. Here you'll find screenshot-driven tours of the CloudAgent interface.
Select a topic from the sidebar to get started, or [return to the main documentation](/).
> **Note:**
Looking for specific recipes? Check out our [Cookbooks](/cookbooks).
# Getting Started
# Getting Started
## Objective
Get up and running with CloudAgent to start managing and securing your cloud infrastructure.
## Overview
CloudAgent is your AI-powered partner for cloud operations. By the end of this guide, you will be able to access the platform and understand the core prerequisites for connecting your cloud environments.
## Accessing the Platform
1. Navigate to [cloudagent.io/login](https://cloudagent.io/login).
2. Enter your **Username** and **Password**, or click **Sign in with Google** to use your Google credentials.
3. Click the **Log in** button (if using username/password).
> **Note:**
If you don't have an account, you can request an invitation by clicking "Sign up".
## Next Steps
Now that you are logged in, the next step is to connect your cloud environment.
**[Go to Account Onboarding](/guide/cloud-setup/aws)** to connect your AWS account and unlock the dashboard features.
# Cloud Setup
# AWS Onboarding
# AWS Onboarding
## Objective
Connect your AWS accounts to CloudAgent to enable monitoring, management, and automated actions.
> **Note:**
**Important**: You must onboard at least one cloud account to see any data in the Dashboard, receive recommendations, or use the Blueprint Builder.
CloudAgent makes it easy to connect your cloud environments and start managing your workloads.
## Adding a Cloud Environment
1. Navigate to **Cloud Setup & Workloads** in the sidebar.
2. Click on **Add Cloud Environment**.
3. **Step 1: Gather Details**: Enter your AWS Account ID and select the desired permission level (e.g., Read-Only, Limited Write, Full Admin).
4. **Step 2: Deploy**: Choose your preferred deployment method. You can launch the CloudFormation stack directly or download the template to deploy manually.
5. **Step 3: Validate**: Once deployed, validate the IAM role connection and give your environment a name.
## Next Steps
- [Azure Onboarding](/guide/cloud-setup/azure) — Connect your Azure subscriptions
- [Permissions & Access Control](/guide/cloud-setup/permissions) — Understand CloudAgent's permission model
- [Managing Workloads](/guide/workloads-governance/workloads) — Create workloads for your connected accounts
# Azure Onboarding
# Azure Onboarding
> **Note:**
Azure support is currently in early access. The onboarding flow is fully functional — additional Azure features (assessments, workload support) are planned for future releases.
## Overview
CloudAgent supports connecting Azure subscriptions alongside your AWS accounts. Once connected, Azure environments appear in your Cloud Environments list and are available to CloudAgent's agent tools for resource discovery and analysis.
## Prerequisites
Before connecting an Azure subscription, you'll need:
- An Azure account with permissions to create App Registrations and assign roles
- The **Tenant ID** for your Azure Active Directory (found in Azure Portal → Azure Active Directory → Overview)
- One or more **Subscription IDs** you want to connect, or a **Management Group ID** for automatic discovery
- Admin consent capability for Microsoft Graph API permissions
## Step 1: Enter Your Tenant Details
In CloudAgent, navigate to **Cloud Setup** and click **+ Add Cloud Environment**, then select **Azure**.
The wizard walks you through four steps. Start by entering:
- **Azure Tenant ID**: Your Azure AD tenant identifier (UUID format)
- **Description** (optional): A friendly label like "Production Azure" or "Dev Tenant"
- **Environment Type**: Choose between Azure Public (default) or Azure US Government
## Step 2: Select Subscription Access
Choose how CloudAgent discovers your subscriptions:
| Mode | How It Works | Best For |
|------|-------------|----------|
| Manual Entry | Enter subscription IDs individually with optional descriptions | Small environments or specific subscriptions |
| Management Group | Provide a management group ID — CloudAgent auto-discovers all subscriptions within it | Large organizations with many subscriptions |
You can always add more subscriptions later by editing the environment.
## Step 3: Create a Service Principal
CloudAgent needs a Service Principal (app registration) in your Azure AD to authenticate. Choose one of three setup methods:
### Option A: Terraform
Download the generated Terraform template and apply it. The template automatically creates the app registration, assigns the required Graph API permissions, and sets up RBAC roles. After running `terraform apply`, the output provides the Client ID and Client Secret you'll need in the next step.
> **Note:**
Terraform templates are tailored to your chosen subscription mode — subscription-level or management group-level — so the correct RBAC scope is applied automatically.
### Option B: PowerShell
Download the PowerShell script and run it in Azure Cloud Shell or a local PowerShell session with the Az module installed. The script performs the same setup as Terraform and outputs the credentials at completion.
### Option C: Manual Setup (Azure Portal)
Follow the step-by-step instructions in the wizard to configure everything through the Azure Portal:
1. **Create an App Registration**: Navigate to Azure AD → App registrations → New registration. Name it something like "CloudAgent" and register it.
2. **Create a Client Secret**: In the app registration, go to Certificates & secrets → New client secret. Copy the secret value immediately — it's only shown once.
3. **Assign Graph API Permissions**: In API permissions, add the following Microsoft Graph (Application) permissions, then grant admin consent:
- `Directory.Read.All`
- `Policy.Read.All`
- `User.Read.All`
- `AuditLog.Read.All`
- `IdentityRiskyUser.Read.All`
- `IdentityRiskyServicePrincipal.Read.All`
- `IdentityRiskEvent.Read.All`
- `UserAuthenticationMethod.Read`
4. **Assign Subscription Roles**: In each subscription (or management group), assign the **Reader** and **Backup Reader** roles to the app registration.
After completing your chosen method, enter the **Client ID** and **Client Secret** in the wizard.
## Step 4: Validate and Save
Click **Test Connection** to verify that CloudAgent can authenticate with your Service Principal. The validation checks that:
- The Service Principal credentials are valid
- The tenant is accessible
- The assigned permissions allow resource access
- (For management group mode) Subscriptions can be discovered
Once validated, give the environment a name and click **Save**. Your Azure environment now appears in Cloud Environments alongside your AWS accounts.
> **Note:**
Store your Client Secret securely. CloudAgent encrypts it before storage, but if you lose the original value, you'll need to create a new secret in Azure and update the environment.
## What You Can Do with Azure Today
With an Azure environment connected, CloudAgent can:
- **Discover resources** across your subscriptions using Azure Resource Graph
- **List subscriptions** and their properties
- **Include Azure environments** in multi-cloud workload definitions
Additional capabilities — including Azure-specific assessments, compliance reports, and agent-driven remediation — are on the roadmap.
## Troubleshooting
**Test Connection fails with authentication error**: Verify that the Client ID and Client Secret are correct. If using manual setup, confirm that admin consent was granted for all Graph API permissions.
**No subscriptions discovered (management group mode)**: Ensure the Service Principal has the Reader role assigned at the management group level, not just individual subscriptions.
**"Insufficient permissions" after successful connection**: The Service Principal likely needs additional role assignments. Verify that both Reader and Backup Reader are assigned at the correct scope (subscription or management group).
**Cannot find Tenant ID**: In the Azure Portal, go to Azure Active Directory → Overview. The Tenant ID is displayed on the overview page.
## Next Steps
- [Permissions & Access Control](/guide/cloud-setup/permissions) — Understand CloudAgent's permission model across all providers
- [Account Onboarding](/guide/cloud-setup/aws) — Connect your AWS accounts
- [Managing Workloads](/guide/workloads-governance/workloads) — Create workloads spanning AWS and Azure environments
# Permissions & Access Control
# Permissions & Access Control
## How CloudAgent Accesses Your Cloud
CloudAgent is a multi-cloud platform that connects to your cloud accounts — including AWS, Azure, and Google Workspace — through provider-specific authentication methods. Each connected account is represented as a **permission profile** (also called a cloud environment). You can connect multiple accounts across different providers and manage them all from a single place.
This page covers the general permission model. For provider-specific onboarding steps, see [Account Onboarding](/guide/cloud-setup/aws) (AWS) and [Azure Onboarding](/guide/cloud-setup/azure).
## AWS IAM Role Setup
When you connect an AWS account, CloudAgent generates a CloudFormation template that creates an IAM role in your account. The setup involves three components:
| Component | Description |
|-----------|-------------|
| IAM Role Name | A dedicated role (e.g., `CloudAgentRole`) created in your account |
| External ID | A unique identifier that prevents unauthorized access — only requests with this ID can assume the role |
| Trust Policy | Allows CloudAgent's service account to assume the role in your account |
At minimum, the role uses the **AWS managed `ReadOnlyAccess` policy**. This is enough to power dashboards, reports, recommendations, and health checks — no additional per-service permissions are required to get started.
Health, cost, inventory, and threat analysis run through background scanner tasks. For AWS, `ReadOnlyAccess` includes the read APIs CloudAgent needs for Cost Explorer, CloudWatch metrics and logs, CloudFormation stack and drift status, and supported database health checks.
### Deployment Options
You can deploy the IAM role using:
1. **One-Click CloudFormation**: Launch the stack directly from CloudAgent's setup wizard — the template is pre-configured with your role name and external ID
2. **Download Template**: Download the CloudFormation JSON/YAML to deploy through your own AWS console or CI/CD pipeline
3. **Terraform**: Generate a Terraform configuration instead of CloudFormation
> **Note:**
The External ID is a critical security feature. It prevents the "confused deputy" problem where an unauthorized party could assume the role. Never share your External ID publicly.
### Built-in Security Restrictions
Every IAM role created by CloudAgent includes automatic restrictions regardless of the permission level you choose:
- **Data Access Restriction**: Denies `secretsmanager:GetSecretValue`, `s3:GetObject`, and `s3:GetObjectVersion` — CloudAgent can see your infrastructure configuration but cannot read your actual data or secrets
- **Temporary Access** (optional): Time-limited role access that automatically expires after a configured duration
## Permission Levels (AWS)
When connecting an AWS account, choose the access level that matches your needs:
| Level | AWS Managed Policy | What It Can Do | Best For |
|-------|-------------------|---------------|----------|
| Read-Only | `ReadOnlyAccess` | View resources, generate reports, run compliance checks, health checks, cost analytics | Monitoring and auditing — most users start here |
| Limited Write | `ReadOnlyAccess` + selective write policies | Everything above, plus automated remediation of specific resource types | Teams adopting automated fixes |
| Full Admin | `ReadOnlyAccess` + broad write policies | Everything above, plus full blueprint deployment and infrastructure management | Full infrastructure automation |
> **Note:**
**Start with Read-Only.** The AWS managed `ReadOnlyAccess` policy is all you need for dashboards, reports, recommendations, health checks, and cost analysis. You can upgrade later as you adopt deployment and remediation features.
Write-level access is only needed when you want CloudAgent to make changes in your account — for example, deploying a blueprint, running a remediation workflow, or enabling a security service like GuardDuty.
## Managing Connected Accounts
Navigate to **Settings** > **Cloud Environments** to view and manage your permission profiles. This page shows all connected cloud accounts across providers (AWS, Azure, Google Workspace).
From this page you can:
- **Add a new account**: Click the add button to start the connection wizard for any supported provider
- **Edit an existing profile**: Update the account name, description, or reconnect with different permissions
- **Delete a profile**: Remove an account connection (this does not affect the role or resources in your cloud account)
- **View security rules**: See which security baselines are applied to this environment
## Connecting a New AWS Account
The connection wizard walks you through three steps:
### Step 1: Account Details
Enter your AWS Account ID and select a permission level. Give the environment a descriptive name (e.g., "Production - us-east-1" or "Sandbox Account").
### Step 2: Deploy the IAM Role
Choose your deployment method (CloudFormation one-click, download template, or Terraform) and deploy the role to your AWS account. The wizard shows the exact role name and External ID that will be configured.
### Step 3: Validate Credentials
After deploying the IAM role, click **Validate** to confirm CloudAgent can successfully assume the role. Validation checks that:
- The role exists with the correct name
- The External ID matches
- The trust policy allows CloudAgent's service account
- The permission level grants the expected access
Once validated, the account appears in your cloud environments and is available for use across all CloudAgent features.
## Authentication Methods
CloudAgent supports two authentication approaches:
| Method | How It Works | Recommended? |
|--------|-------------|:------------:|
| IAM Role (STS AssumeRole) | CloudAgent assumes a role in your account using STS with an External ID | Yes |
| IAM User Credentials | Access key and secret key for a dedicated IAM user | Legacy only |
IAM roles are strongly recommended because they don't require long-lived credentials, support automatic rotation, and provide better auditability through CloudTrail.
## Multi-Account and Multi-Cloud Management
CloudAgent supports connecting multiple cloud accounts — across AWS, Azure, and other providers — under a single user profile. Each account operates as an independent permission profile with its own:
- Permission level and IAM role
- Security rules and baselines
- Deployment preferences
- Architecture preferences
When using features like the Cost Dashboard, Health Dashboard, or Reports, you select which environment (account) to analyze. Workloads can span multiple environments by selecting multiple accounts during workload configuration.
## Credential Rotation
Since CloudAgent uses IAM role assumption (not stored credentials), credential rotation is handled automatically by AWS STS. Temporary session credentials are generated on each API call and expire after a short duration.
If you need to update the IAM role:
1. Modify the CloudFormation stack or IAM role directly in your AWS account
2. Return to CloudAgent's Cloud Environments page
3. Click **Edit** on the permission profile
4. Click **Validate** to confirm the updated role works correctly
## Troubleshooting
**Validation fails after deploying the IAM role**: Verify that the CloudFormation stack completed successfully in your AWS account. Check that the role name and External ID match exactly what CloudAgent's wizard specified.
**"Access Denied" errors during scans or reports**: This usually means the IAM role is missing or misconfigured. The AWS managed `ReadOnlyAccess` policy covers all read operations CloudAgent needs. If you see access errors on write operations (remediation, deployment), upgrade to Limited Write or Full Admin.
**Scanner result is pending**: Background scanner tasks may take a few minutes to write health, cost, inventory, or threat artifacts. Refresh the dashboard or report after the task completes.
**Cannot see resources from a connected account**: Ensure the permission profile is validated (green checkmark) in Cloud Environments. If the checkmark is missing, click Edit and re-run the validation step.
**Multiple accounts showing the same data**: Each permission profile should point to a different AWS Account ID. Check your Cloud Environments list to ensure accounts aren't duplicated.
## Next Steps
- [Account Onboarding](/guide/cloud-setup/aws) — Step-by-step guide for your first AWS account connection
- [Artifact Analysis](/guide/reports-insights/artifact-analysis) — Understand how scanner tasks produce health, cost, inventory, and threat artifacts
- [Security Rules & Baselines](/guide/workloads-governance/security-baselines) — Configure compliance rules for connected accounts
- [Governance & Architecture](/guide/workloads-governance/governance) — Set up deployment controls and architecture preferences
- [Managing Workloads](/guide/workloads-governance/workloads) — Create workloads that span your connected accounts
# Dashboards
# Overview
# Dashboard Overview
## Objective
Gain a comprehensive view of your cloud resources, security posture, and agent activities.
Once logged in, you will see the **Dashboard Overview**. This is your central hub for managing your cloud workforce.
> **Note:**
**Prerequisite**: The dashboard will appear empty until you connect a cloud account. Please complete the [Account Onboarding](/guide/cloud-setup/aws) step first.
## Key Features
### 1. Stats Overview
At the top of the dashboard, you'll find a quick summary of your environment:
- **Activity**: Total count of active agents, workflows, and generated reports.
- **Environments & Workloads**: Number of connected AWS accounts and managed workloads.
- **Recommendations**: Active recommendations categorized by priority (Critical, High, Medium, Low).
### 2. Smart Recommendations
The dashboard automatically categorizes findings into actionable groups:
- **Critical Security**: High-priority security issues that need immediate attention.
- **Cost Savings**: Opportunities to reduce your cloud spend.
- **Resource Cleanup**: Identification of unused or idle resources.
- **Compliance**: Audit items mapped to frameworks like SOC 2 and HIPAA.
- **Platform Insights**: Suggestions to maximize the value of CloudAgent.
### 3. Scheduled Workflows
View and manage your automated tasks:
- **Active**: Workflows currently running on a schedule (e.g., daily backups).
- **Paused**: Scheduled tasks that have been temporarily disabled.
- **All Activities**: A complete list of all scheduled operations.
### 4. Latest Activity
A real-time feed of what your agents are doing:
- **Agents**: Status updates from individual agents.
- **Workflows**: Progress of complex, multi-step workflows.
- **Waiting on User**: Tasks that require your approval to proceed.
- **Done**: Completed actions and their results.
### 5. Reports
CloudAgent creates detailed security reports for your cloud account, including **cost** and **compliance** reports (such as **SOC 2** and **HIPAA**).
> **Note:**
Get the full list of available reports at [cloudagent.io/libraries/all-reports](https://cloudagent.io/libraries/all-reports).
## Key Sections
* **Overview**: A summary of your cloud resources and agent activity.
* **Cloud Setup & Workloads**: Manage your cloud infrastructure connections.
* **Recommendations**: AI-driven suggestions for optimizing your cloud environment.
* **My Workflows**: View and manage your automated workflows.
* **Blueprints & Agents**: Create and manage infrastructure blueprints.
* **Reports**: Generate and view compliance reports.
* **My Account**: Manage your profile and settings.
## Next Steps
- [Cost Dashboard](/guide/dashboards/cost) — Analyze your cloud spending and savings opportunities
- [Health Dashboard](/guide/dashboards/health) — Monitor resource health across your environments
- [Recommendations](/guide/reports-insights/recommendations) — Act on prioritized findings
# Command Center
# Command Center
## Objective
Use Command Center to work with CloudAgent conversationally while keeping live product context in scope. Command Center is where you combine environments, workloads, reports, recommendations, and executive summaries into one guided operating surface.
## Accessing Command Center
Navigate to **Command Center** in the sidebar, or go directly to `/dashboard/cloudagent`.
Command Center supports two main paths:
| Path | Use It For |
|------|------------|
| Recommended By CloudAgent | Start from personalized recommendation cards and guided next actions |
| Type a question or task | Ask for infrastructure help, investigation, review, or action in your own words |
## Scope and Context
Before sending a prompt, you can add product context so CloudAgent works against the right objects.
Supported scope types include:
| Scope Type | Typical Use |
|------------|-------------|
| Environments | Review health, cost, security posture, and account-level findings |
| Workloads | Focus on one application or stack and the resources tied to it |
| Reports | Ground the conversation in an existing compliance or analysis report |
Command Center enforces scope limits so the conversation stays focused. If too much is selected, narrow the scope before continuing.
## What You Can Review Inline
Command Center can load and preview several product artifacts without forcing you to navigate away first:
- recommendations and suggested follow-up actions
- report previews and summaries
- executive summary previews for environments and workloads
- health findings and resource-level issues
- cost analysis results and optimization signals
This is especially useful when a user needs to compare multiple sources before deciding whether to run a blueprint, start a workflow, or request approval.
## Working from Recommendations
When you open Command Center from a recommendation or choose **Recommended By CloudAgent**, the experience is tuned for triage:
1. review the recommendation and its priority
2. inspect affected resources or supporting context
3. preview linked reports or executive summaries when available
4. decide whether to dismiss, investigate further, or remediate
Some recommendations open directly into a remediation or blueprint flow. Others are better handled as a question to Command Center with the relevant environment or workload already in scope.
## Report and Executive Summary Previews
Command Center can preview:
- report summaries
- executive summaries for environments
- executive summaries for workloads
Use report previews when you need evidence from a specific scan or compliance result. Use executive summary previews when you need a faster roll-up for stakeholder communication or decision support.
## Waiting on User and Approval States
Command Center also surfaces long-running and human-in-the-loop states. Common examples include:
- a workflow or blueprint is waiting for approval
- a background scan is still processing
- a report or summary has not finished loading
- a follow-up question is required before a state-changing action can proceed
If a task is paused for approval, review the proposed action and supporting context before continuing. This is the right place to stop an automated flow before it changes production infrastructure.
> **Note:**
Command Center is strongest when you add only the environments, workloads, and reports needed for the decision at hand. Treat it as an operating surface, not a catch-all chat window.
## Common Use Cases
### Investigate an environment
Add one environment to scope, review health or cost context, and ask CloudAgent to summarize current issues and next actions.
### Review a workload before remediation
Add the workload and any related report, then ask CloudAgent to explain the current findings, likely impact, and safest remediation path.
### Prepare for an approval decision
Open the waiting task, inspect the recommendation, report preview, or executive summary, then decide whether to continue, pause, or cancel.
## Troubleshooting
**Context feels incomplete**: Add the workload, environment, or report explicitly instead of relying on a generic question.
**A report preview is missing**: Confirm the report has completed and that it is in the current scope.
**An executive summary does not appear**: Generate or refresh the executive summary first, then reopen the preview.
**A task is still pending**: The backing workflow, report, or scanner may still be running. Wait for the product artifact to finish and refresh the page.
## Next Steps
- [Executive Summaries](/guide/reports-insights/executive-summaries) — Understand environment and workload summaries used in Command Center
- [Recommendations](/guide/reports-insights/recommendations) — Review the recommendation flows that often start Command Center sessions
- [My Workflows](/guide/automation/workflows) — Automate the follow-up actions you commonly take after review
# Cost Dashboard
# Cost Dashboard
## Objective
Monitor and optimize your cloud spending with real-time cost analytics, forecasting, and actionable savings recommendations.
The Cost Dashboard consolidates data from multiple sources into a single view of your spending. For AWS accounts, it pulls from AWS Cost Explorer, Anomaly Detection, Compute Optimizer, Savings Plans, and Cost Optimization Hub. CloudAgent's own assessment engine also generates cost-related recommendations independently — so you'll see actionable findings even if some of those AWS services are not enabled in your account.
## Accessing the Cost Dashboard
Navigate to **Dashboards → Cost** in the sidebar, or go directly to `/dashboards/cost`.
> **Note:**
Cost data may take a few minutes to load after connecting a new AWS account. If the dashboard appears empty, click the **Refresh** button and ensure your connected role has the AWS managed `ReadOnlyAccess` policy — this covers all the permissions CloudAgent needs for cost data.
The Cost Dashboard works with AWS accounts connected through [Cloud Environments](/guide/cloud-setup/permissions). The dashboard pulls data from several AWS services — the more you have enabled, the richer the data:
| Data Source | Description | What Happens If Not Enabled |
|-------------|-------------|----------------------------|
| AWS Cost Explorer | Historical spend data and trends | Enabled by default on all AWS accounts. If spend charts appear empty, verify your IAM role permissions and click Refresh. |
| AWS Anomaly Detection | Unusual spending pattern alerts | The anomaly section will not appear. You'll still see cost data from other sources. |
| AWS Compute Optimizer | EC2, RDS, and EBS rightsizing insights | Rightsizing recommendations will not be available. CloudAgent's own assessment engine may still surface cost findings independently. |
| AWS Cost Optimization Hub | Cross-service optimization opportunities | This section will not appear. Other recommendation sources still function normally. |
> **Note:**
The dashboard displays status indicators for each data source so you can quickly see which services are active and which need to be enabled. Even without any AWS cost services configured, CloudAgent's built-in assessment engine can identify cost optimization opportunities through its own checks.
## Key Metrics
The top of the dashboard displays summary cards with your most important cost data:
| Metric | Description |
|--------|-------------|
| Monthly Spend | Total spend for the current and previous months with a trend comparison |
| Daily Average Spend | Average daily cost over the lookback period (default 90 days) |
| Total Period Spend | Aggregated spending across the entire analysis window |
| Spend Trend | Percentage change comparing the first half vs. second half of the period |
| Estimated Savings | Total potential monthly savings from all recommendation types |
## Understanding Your Cost Data
### Spend Over Time
The daily spend trend chart shows your spending as an area chart over the lookback period. Hover over any point to see the exact daily amount. This view helps you spot gradual increases, seasonal patterns, or sudden spikes.
### Spend by Service
A horizontal bar chart breaks down your top 8 cloud services by total spend, sorted from highest to lowest. For AWS accounts, common leaders include EC2, RDS, S3, and Lambda. Use this to identify which services drive the most cost.
### Spend by Linked Account
For organizations with multiple cloud accounts, the vertical bar chart shows cost distribution across up to 10 linked accounts. This is particularly useful for chargeback, cost allocation, and identifying accounts with unexpected growth.
## Filtering and Controls
You can adjust the dashboard view using these controls:
- **Environment Selector**: Choose which cloud account or permission profile to analyze. If you have multiple accounts connected, switch between them here.
- **Refresh**: Force a fresh data pull from your cloud provider's APIs. The dashboard caches data to reduce API calls, so use this when you need the latest numbers.
- **Lookback Period**: The default analysis window is 90 days. This determines how far back the trend chart and calculations extend.
Cost analysis runs as an asynchronous scanner task. After you click **Refresh**, CloudAgent stores the generated cost artifact and the dashboard loads that stored result. If the artifact is still being created, the dashboard may show a pending state until the scan completes.
## Anomaly Detection
When AWS Cost Anomaly Detection is configured in your account, the dashboard surfaces unusual spending patterns automatically. Each anomaly shows:
- The AWS service where the anomaly occurred
- The date range of the unusual activity
- Expected spend vs. actual spend
- The overspend impact amount
- A confidence score
If you haven't enabled AWS Cost Anomaly Detection, this section will not appear. To enable it, set up Cost Anomaly Detection monitors in the AWS Billing & Cost Management console. Once configured, anomalies will surface here automatically on your next dashboard refresh.
Clicking an anomaly opens a direct link to the AWS Cost Anomaly Detection console for deeper investigation.
## Savings Recommendations
The Cost Dashboard aggregates optimization recommendations from multiple sources. For AWS accounts, these include three native AWS services plus CloudAgent's own assessment engine. If a particular AWS service is not enabled, that section simply won't appear — the remaining sources continue to function normally.
### Rightsizing Recommendations
Sourced from AWS Compute Optimizer, these suggest changes to your EC2 instances, RDS databases, and EBS volumes. If Compute Optimizer is not enabled in your account, this section will not appear — enable it in the AWS console to get rightsizing insights.
| Column | Description |
|--------|-------------|
| Resource ID | The specific instance or volume to modify |
| Current Type | Your current instance type or configuration |
| Recommended Type | The suggested target configuration |
| Monthly Savings | Estimated cost reduction per month |
| Action | Modify, Terminate, or Migrate |
### Savings Plans Recommendations
Based on your usage patterns, AWS recommends commitment-based discounts:
| Column | Description |
|--------|-------------|
| Plan Type | Compute Savings Plan, EC2 Instance, or SageMaker |
| Term | 1-year or 3-year commitment |
| Payment Option | All Upfront, Partial Upfront, or No Upfront |
| Hourly Commitment | Dollar amount per hour to purchase |
| Monthly Savings | Estimated savings after commitment |
### Cost Optimization Hub
Additional cross-service recommendations that combine insights from multiple AWS optimization tools into unified suggestions.
## Taking Action on Cost Findings
Once you identify cost optimization opportunities:
1. Review the specific recommendations in the dashboard
2. Navigate to **Recommendations** for a prioritized action list across all categories
3. Create a remediation workflow to automate the fix — see [My Workflows](/guide/automation/workflows) for scheduling automated responses
4. Re-run the cost analysis after implementing changes to verify savings
> **Note:**
**Tip**: Create a scheduled workflow to generate weekly cost reports and email them to your finance team automatically.
## Troubleshooting
**Cost data appears delayed**: AWS Cost Explorer data typically updates once per day. If you connected a new account, allow 24-48 hours for historical data to populate.
**Missing cost data for an account**: Verify the permission profile is validated on the [Cloud Setup](/guide/cloud-setup/aws) page — the AWS managed `ReadOnlyAccess` policy covers all the permissions CloudAgent needs for cost data. Also try clicking **Refresh** to force a fresh data pull.
**Cost analysis is not ready yet**: A new cost scan may still be running. Wait a few minutes, then refresh the dashboard or rerun the analysis for the selected environment.
**No recommendations showing**: AWS services like Compute Optimizer and Cost Optimization Hub need 14+ days of usage data before generating recommendations. If you haven't enabled these services yet, only CloudAgent's own assessment engine recommendations will appear.
**Anomalies section not visible**: This section only appears when AWS Cost Anomaly Detection is both configured in your account and has detected anomalies. If you haven't set up Cost Anomaly Detection monitors yet, enable them in the AWS Billing console.
## Next Steps
- [Artifact Analysis](/guide/reports-insights/artifact-analysis) — Understand how stored cost artifacts and pending states work
- [Recommendations](/guide/reports-insights/recommendations) — View and act on prioritized optimization findings
- [My Workflows](/guide/automation/workflows) — Schedule automated cost reports and remediation
- [Reports](/guide/reports-insights/reports) — Generate formal compliance and cost reports for stakeholders
# Health Dashboard
# Health Dashboard
## Objective
Monitor the operational health of your cloud resources across all workloads and environments from a single dashboard. Currently, health checks are available for AWS resources.
The Health Dashboard aggregates health check results from your tracked resources and cloud environments, giving you a real-time view of what's healthy, what has issues, and what hasn't been checked yet.
## Accessing the Health Dashboard
Navigate to **Health Dashboard** in the sidebar, or go directly to `/dashboard/health`.
## Key Health Metrics
The top of the dashboard displays summary cards:
| Metric | Description |
|--------|-------------|
| Health Score | Percentage of evaluated resources that are healthy. Calculated as `healthy / (healthy + unhealthy) × 100%` |
| Total Resources | Count of all resources being monitored across workloads and environments |
| Healthy | Resources where all health checks passed |
| Issues | Resources with one or more failed health checks |
| Data Sources | Number of workloads and cloud environments providing health data |
The Health Score uses color-coded indicators: green when 80% or above, amber between 50-79%, and red below 50%. Resources that haven't been checked yet are excluded from the score calculation.
## Understanding Health Statuses
Each resource is assigned one of four statuses:
| Status | Meaning |
|--------|---------|
| **Healthy** | All health checks passed — the resource is operating as expected |
| **Issues** | One or more health checks failed — investigation or remediation needed |
| **Not Checked** | The resource has never been evaluated — run a health check to assess it |
| **Skipped** | The resource type is not supported for health checks or the check is not applicable |
## Resource-Level Health Details
Click any resource in the table to expand its details. Each resource shows:
- **Resource identity**: Name, type (e.g., `AWS::ECS::Service`), ARN, region, and account ID
- **Associated workloads**: Which workloads track this resource, with links to workload details
- **Individual health checks**: A breakdown of each check that was run, including:
- Check name and category (availability, errors, configuration, capacity, runtime-eol)
- Pass or fail status
- Summary explanation of the result
- Detailed metrics (expandable)
- Timestamp of when the check was last evaluated
> **Note:**
Health checks cover multiple categories: availability (is the resource running?), errors (are there failures in logs?), configuration (is the setup correct?), capacity (is the resource under pressure?), and runtime lifecycle.
## Health Check Coverage
CloudAgent health checks include common AWS compute, storage, database, and delivery services. Coverage continues to expand, and unsupported resource types appear as **Skipped** instead of reducing the health score.
Recent AWS coverage includes:
| Area | Examples of Checks |
|------|--------------------|
| CloudFormation | Failed stack status, recent failed stack events, stack drift status |
| RDS | DB instance and cluster status, free storage headroom, replica lag, deadlocks, exported log errors |
| Amazon DocumentDB | Cluster and instance status, global replication lag, connection headroom, low-memory throttling, replica status, exported log errors |
| Amazon Neptune | Cluster and instance status, global replication lag, main request queue pressure, replica status, exported log errors |
CloudFormation drift checks reuse a drift result from the last 24 hours when one is available. If no recent result exists, CloudAgent starts drift detection and reports the final status when the AWS drift operation completes.
## Filtering Resources
Use the filter controls to narrow down the resource list:
- **Search**: Filter by resource name, type, ARN, resource ID, workload name, or environment name
- **Status filter**: Show only Healthy, Issues, Not Checked, or Skipped resources
- **Workload filter**: Limit the view to resources belonging to a specific workload
## Running Health Checks
To refresh health data, click the **Refresh** button and choose between refreshing workload resources or environment resources. Before the check runs, you can configure:
### Lookback Period
Choose how far back to analyze CloudWatch metrics and alarms: 1, 3, 7 (default), 14, 30, or 60 days. A longer lookback catches intermittent issues but takes more time to process.
### CloudWatch Log Checks
When enabled, CloudAgent searches CloudWatch logs for error keywords like "error", "fail", and "exception". This is off by default because it can increase AWS API costs for workloads with large log volumes.
### Force Refresh
When enabled (the default), a fresh report is generated regardless of cache. When disabled, the most recent report is reused if it was generated within the last 24 hours.
> **Note:**
Enabling CloudWatch Log Checks on workloads with high log volume may increase your AWS API costs. Use the lookback period to limit the scope.
## Data Freshness
Click the data freshness indicator to see when each workload and environment was last checked. The modal shows:
- Last health check timestamp for each data source (displayed as relative time, e.g., "2h ago")
- Resource count per data source
- Individual refresh buttons for each workload or environment
- Bulk refresh option for all sources at once
Data is considered fresh if generated within the last 24 hours. Sources showing "Never checked" need an initial health check run.
## Pending Results
Health analysis runs asynchronously. While a new scanner task is still writing its results, the dashboard may show a pending or not-ready state for the selected workload or environment. Refresh again after the scan completes to load the stored health artifact.
## Taking Action on Health Issues
When the dashboard surfaces resources with issues:
1. Click the resource to view its failed health checks and understand the root cause
2. Navigate to **Recommendations** to see if CloudAgent has suggested a fix
3. Create a remediation workflow to address the issue — either manually or through an automated blueprint
4. Re-run the health check after remediation to confirm the fix
## Troubleshooting
**Health score seems low despite no critical issues**: The score includes all evaluated resources. Check if non-critical resources (like dev/test environments) are pulling the score down. Use workload filters to see production health separately.
**Resources showing "Not Checked"**: These resources haven't had health checks run yet. Click Refresh and select the appropriate workload or environment to evaluate them.
**Health data not updating**: Verify that the permission profile for the environment is validated and uses at least the AWS managed `ReadOnlyAccess` policy, which covers the CloudWatch permissions health checks require. Also check that force refresh is enabled if you're seeing stale data.
**CloudFormation drift stays pending or unknown**: Drift detection can take time in AWS and only runs for supported stack statuses. If another drift operation is already in progress, CloudAgent reuses the latest available stack drift status until the operation completes.
**Checks showing "Skipped"**: Some resource types don't have health checks available yet. CloudAgent continuously expands its check coverage.
## Next Steps
- [Artifact Analysis](/guide/reports-insights/artifact-analysis) — Understand how stored health artifacts and pending states work
- [Recommendations](/guide/reports-insights/recommendations) — Act on health-related findings with prioritized remediation steps
- [Managing Workloads](/guide/workloads-governance/workloads) — Configure which resources are tracked and monitored
- [My Workflows](/guide/automation/workflows) — Schedule periodic health checks as automated workflows
# Threat Management
# Threat Management
> **Note:**
Threat Management is currently in preview. The dedicated dashboard is under active development — features described here reflect both current capabilities and planned enhancements.
## Overview
Threat Management in CloudAgent brings together cloud-native security services to help you detect, investigate, and respond to threats across your environments. Currently, threat detection integrations are available for AWS. While the full Threat Management dashboard is coming soon, several threat detection capabilities are already available through CloudAgent's existing features.
## Current Threat Detection Capabilities
CloudAgent currently supports threat detection through its **Recommendations** and **Reports** systems. The platform evaluates your environments against threat detection best practices and flags gaps in your security posture.
Threat analysis uses stored scanner artifacts for each connected AWS environment. When you refresh threat data, CloudAgent starts a scanner task and loads the stored result after it is available. Until then, the environment may show a pending or not-ready state.
### Supported AWS Security Services
For AWS accounts, CloudAgent integrates with the following threat detection services:
| AWS Service | What It Does | CloudAgent Integration |
|-------------|-------------|----------------------|
| AWS GuardDuty | Continuous threat monitoring using ML-based anomaly detection across CloudTrail, VPC Flow Logs, and DNS | Recommendations to enable and configure GuardDuty |
| AWS Security Hub | Centralized security findings aggregation from multiple AWS services | Recommendations to enable Security Hub and review findings |
| AWS IAM Access Analyzer | Identifies resources shared with external entities and validates IAM policies | Recommendations to enable Access Analyzer for each region |
### How Threat Detection Works Today
1. **Recommendations**: Navigate to the [Recommendations](/guide/reports-insights/recommendations) page and filter by the **Threat Detection** category. For AWS accounts, CloudAgent checks whether GuardDuty, Security Hub, and IAM Access Analyzer are enabled and properly configured. If these services aren't enabled yet, CloudAgent will surface recommendations to turn them on.
2. **Compliance Reports**: Several [reports](/guide/reports-insights/reports) include threat detection controls:
- **CIS AWS Foundations Benchmark** checks for GuardDuty and Security Hub enablement
- **NIST 800-53** and **NIST CSF** reports assess threat monitoring controls
- **SOC2** reports evaluate security monitoring and incident response readiness
3. **Automated Remediation**: When CloudAgent identifies that a threat detection service is not enabled, you can use a blueprint or workflow to automatically enable it. Each recommendation includes a remediation blueprint that can be executed directly.
4. **Artifact Analysis in Workflows**: Workflows can analyze existing threat artifacts alongside cost, health, and inventory data. This is useful when you want a recurring workflow to summarize current threat findings without running a new report blueprint first.
## Planned Capabilities
The upcoming Threat Management dashboard will provide a centralized view for:
- **Active Threats**: Real-time feed of GuardDuty findings and Security Hub alerts, prioritized by severity
- **Threat Timeline**: Visual timeline of security events across accounts and regions
- **Investigation Workflows**: Click-through investigation from alert to affected resources with contextual information
- **Automated Response**: Pre-built response blueprints for common threat types (compromised credentials, unusual API activity, network anomalies)
- **Cross-Account Visibility**: Unified threat view across all connected AWS accounts
## Getting Started with Threat Detection
Even before the full dashboard launches, you can set up a strong threat detection foundation:
1. **Enable GuardDuty**: Go to [Recommendations](/guide/reports-insights/recommendations), find the "Enable AWS GuardDuty" recommendation, and run the remediation blueprint
2. **Enable Security Hub**: Similarly, enable Security Hub through the recommendations workflow
3. **Enable IAM Access Analyzer**: Set up Access Analyzer to monitor for unintended external resource sharing
4. **Run a Security Report**: Generate a CIS AWS Foundations Benchmark or NIST CSF report to assess your overall threat readiness
5. **Schedule Ongoing Checks**: Create a [workflow](/guide/automation/workflows) to run threat detection checks weekly
> **Note:**
**Tip**: Enabling GuardDuty, Security Hub, and IAM Access Analyzer across all your connected accounts gives CloudAgent the broadest threat visibility when the full dashboard launches.
## Next Steps
- [Artifact Analysis](/guide/reports-insights/artifact-analysis) — Understand how stored threat artifacts and pending states work
- [Recommendations](/guide/reports-insights/recommendations) — Review and act on threat detection recommendations
- [Reports](/guide/reports-insights/reports) — Run compliance reports that include threat monitoring controls
- [Blueprints & Agents](/guide/automation/blueprints) — Use remediation blueprints to enable security services
- [My Workflows](/guide/automation/workflows) — Schedule automated threat posture checks
# Workloads & Governance
# Managing Workloads
# Managing Workloads
## Objective
View, manage, and optimize your deployed applications and infrastructure stacks.
The **Cloud Setup & Workloads** section allows you to view and manage your cloud infrastructure and applications.
## Viewing Workloads
To view your workloads:
1. Navigate to **Cloud Setup & Workloads** in the sidebar.
2. You will see a list of all connected cloud environments and deployed workloads.
## Workload Details
Click on any workload in the list to view its details. The details view provides comprehensive information about the workload's status, resources, and configuration.
### Key Tabs
* **Overview**: General information about the workload, including the Diagram Preview.
* **Tracked Resources**: A list of all cloud resources (e.g., S3 buckets, IAM roles, CloudFormation stacks) associated with this workload.
* **Deployment Settings**: Configuration options for how the workload is deployed.
* **Governance**: Policies and rules applied to the workload.
* **Architecture Preferences**: Settings related to the architectural design of the workload.
* **Security Rules**: Security configurations and firewall rules.
The workload detail view is where CloudAgent ties together topology, tracked resources, recommendations, reports, and environment context. It is the main place to understand what the workload contains and which cloud environments back it.
### Diagram Preview
The **Diagram Preview** panel provides a visual representation of your workload's architecture. It displays all the AWS resources and their relationships in an easy-to-understand diagram.
- **Auto-Generated**: The diagram is automatically generated based on tracked resources.
- **Expandable View**: Click the **Expand** button to open a full-screen view for detailed inspection.
- **Resource Icons**: Each AWS service (Lambda, S3, DynamoDB, etc.) is represented with its official icon.
- **Timestamps**: Shows when the diagram was last generated.
> **Note:**
**Tip**: Use the expanded diagram view during architecture reviews or when onboarding new team members to quickly understand the infrastructure layout.
Because the diagram is generated from tracked resources, it becomes more useful as workload discovery improves. If the diagram looks incomplete, review the tracked resources list first.
### Resource Environment Context
Tracked resources can include the AWS account ID and permission profile that owns the resource. This helps CloudAgent connect workload resources back to the right environment for health checks, cost context, recommendations, reports, and workflows.
When CloudAgent discovers resources from CloudFormation stacks, it keeps stack-derived resources linked to the selected environment. This is especially important for workloads that span multiple accounts or regions.
## Tracked Resources
Tracked resources are the foundation for workload-level analysis. This table is where CloudAgent decides which resources belong to the workload for:
- health checks
- recommendations
- architecture diagrams
- reports
- workflow targeting
Tracked resources can include compute, storage, networking, IAM, database, and CloudFormation-managed resources. If a resource is missing here, it will usually be missing from downstream health, recommendation, and diagram views too.
### Recommendations and Reports
The workload details page also includes:
* **Top 5 Environment Recommendations**: Priority-ranked suggestions specific to this workload's environment.
* **Reports**: Compliance reports (PCI DSS, CIS Benchmarks) with status indicators and quick access to view details.
The reports table shows workload-relevant scans by environment, status, and update time. Use **Run New Report** to start a fresh report from the library, or **View Report** to open an existing completed result.
## Recommendations in Workloads
The workload details page can show both:
- **Workload recommendations** tied directly to tracked workload resources
- **Top 5 environment recommendations** inherited from the backing cloud environment
Use workload recommendations when you want findings tightly scoped to the application or stack. Use environment recommendations when the issue is broader and affects the account, region, or shared platform around the workload.
Each recommendation row includes:
| Field | Description |
|-------|-------------|
| Recommendation | The finding title or suggested improvement |
| Priority | Critical, High, Medium, or Low |
| Resources | How many resources are affected |
| Updated | When the finding was last refreshed |
| Remediation | Direct action into the recommendation flow or blueprint run |
## Multi-Environment Workloads
A workload can span multiple environments, accounts, or regions. In that model:
- tracked resources remain linked back to their source environment
- health and cost context can be reviewed by environment and by workload
- reports may be run against one or more workload environments
- workflows can use the workload as an organizing layer while still executing per environment
This separation matters when a workload contains shared services, regional replicas, or production and non-production environments under one application boundary.
## Common Troubleshooting
**A workload has no recommendations**: Confirm the tracked resources list is populated and the backing environment has current recommendation or scanner data.
**A workload report table is empty**: Reports appear after they are run for the workload's environments. Use **Run New Report** from the workload page or the main reports library.
**The diagram is missing services**: Review tracked resources and CloudFormation-linked discovery first. The diagram only reflects what CloudAgent currently associates with the workload.
**The wrong account context is shown**: Check the permission profile and environment linkage for the workload resources. Multi-account workloads depend on correct environment association.
## Next Steps
- [Security Rules & Baselines](/guide/workloads-governance/security-baselines) — Configure compliance rules for your workloads
- [Governance & Architecture](/guide/workloads-governance/governance) — Set deployment controls and architecture preferences
- [Artifact Analysis](/guide/reports-insights/artifact-analysis) — Understand how workload reports and findings are generated from stored artifacts
- [Recommendations](/guide/reports-insights/recommendations) — View findings across your workloads
# Security Rules & Baselines
# Security Rules & Baselines
## What Are Security Baselines?
Security baselines are collections of predefined compliance checks that validate your cloud infrastructure against security best practices. When applied to a workload, these rules are enforced at deployment time — blocking any infrastructure that violates your selected standards before it reaches your cloud account.
For AWS environments, CloudAgent includes **192 security rules** covering 42 AWS services across 11 security categories. Rules are enforced using AWS CloudFormation Guard, which validates your CloudFormation or Terraform templates against enabled rules during blueprint generation. Additional provider-specific rules will be added as CloudAgent expands its multi-cloud support.
## Available Presets
To get started quickly, CloudAgent provides five security presets that enable progressively stricter rule sets:
| Preset | Rules Enabled | Best For |
|--------|:------------:|----------|
| None | 0 | Unrestricted deployments (not recommended) |
| Relaxed Sandbox | 4 | Quick experiments and proof-of-concept work |
| Basic Security | 8 | Environments with minimal compliance needs |
| Development | 12 | Dev/staging environments with standard protections |
| Production | 21 | Production workloads requiring comprehensive controls |
| All Best Practices | 192 | Maximum security posture across all services |
> **Note:**
Presets are starting points. After selecting one, you can enable or disable individual rules to match your organization's specific requirements.
### What Each Preset Covers
**Relaxed Sandbox (4 rules)**: EC2 detailed monitoring, CloudTrail enabled, and RDS public access restrictions. The minimum to maintain basic visibility.
**Basic Security (8 rules)**: Adds security group requirements, S3 public access blocks, and RDS/Redshift public access restrictions. Covers the most common misconfiguration risks.
**Development (12 rules)**: Adds CloudTrail file validation, S3 bucket logging, VPC Flow Logs, and HTTPS/TLS enforcement. Ensures logging and encryption-in-transit are in place.
**Production (21 rules)**: Adds encryption at rest (EBS, RDS, S3), database backups, multi-AZ support, auto-scaling, and cross-region replication. Comprehensive coverage for workloads handling real data.
**All Best Practices (192 rules)**: Every available rule across all 42 supported services. Best for high-compliance environments like healthcare, finance, or government.
## Rule Categories
Rules are organized into 11 categories:
| Category | Description | Example Rules |
|----------|-------------|---------------|
| Encryption | At-rest encryption for storage and databases | EBS volume encryption, RDS encryption, S3 default encryption |
| Encryption In-Transit | TLS/SSL enforcement for data in motion | ALB HTTPS redirect, CloudFront TLS, API Gateway TLS |
| Public Access | Prevent unintended public exposure | S3 block public access, RDS no public access, Redshift no public access |
| Network Access Control | Security group and network configuration | Restricted SSH/RDP, VPC Flow Logs, no unrestricted ingress |
| Identity & Access Management | IAM policies and access patterns | MFA enforcement, access key rotation, least-privilege policies |
| Logging | Audit trail and monitoring configuration | CloudTrail enabled, S3 access logging, VPC Flow Logs |
| Backup | Data protection and recovery | RDS automated backups, cross-region replication, delete protection |
| Resiliency | High availability and fault tolerance | Multi-AZ deployments, auto-scaling, load balancing |
| Cost & Billing | Cost governance controls | EBS optimization, instance rightsizing |
| No Plain Text Passwords | Secrets management | No hardcoded credentials in templates or parameters |
| Other Best Practices | General operational excellence | Detailed monitoring, tagging standards |
## How Rules Are Applied
Security rules are enforced during the deployment pipeline:
1. **Configure**: Select a preset or customize individual rules in the workload's **Security Rules** tab
2. **Save**: Rule configuration is stored with the workload definition
3. **Deploy**: When you create infrastructure via a blueprint, CloudAgent generates a CloudFormation or Terraform template
4. **Validate**: CloudFormation Guard checks the template against all enabled rules
5. **Block or Proceed**: If violations are found, deployment is blocked with a detailed explanation. If all checks pass, deployment proceeds
> **Note:**
Security rules are preventive — they block non-compliant deployments before resources are created. They do not retroactively scan existing infrastructure. Use [Reports](/guide/reports-insights/reports) for post-deployment compliance scanning.
## Configuring Security Rules
### Selecting a Preset
1. Navigate to your workload and open the **Security Rules** tab
2. Choose a preset from the dropdown (e.g., "Production")
3. The corresponding rules are automatically enabled
4. Click **Save** to apply
### Customizing Individual Rules
After selecting a preset, you can fine-tune:
- **Group by Category or Service**: Toggle the view to see rules organized by security category (e.g., Encryption, Logging) or by AWS service (e.g., S3, EC2, RDS)
- **Toggle individual rules**: Use the switch next to each rule to enable or disable it
- **Enable/disable entire categories**: Use the category-level toggle to enable or disable all rules in a group
- **Enable All / Disable All**: Use the global toggle to quickly enable or disable every rule
### Understanding Rule Details
Each rule displays:
- **Title**: A descriptive name (e.g., "EBS Volume Encryption Key Rule")
- **Description**: What the rule checks and why it matters
- **Service**: The AWS service this rule applies to
- **Category**: The security category (Encryption, Logging, etc.)
> **Note:**
Rule definitions are maintained by CloudAgent and cannot be modified. You can only enable or disable rules — this ensures consistent compliance standards across your organization.
## Viewing Compliance Against Rules
When a deployment is blocked by a security rule violation, the preview shows:
- Which rule was violated
- Which resource in the template caused the violation
- The reason for the failure
- A suggested fix
After addressing violations, resubmit the deployment for re-validation.
For ongoing compliance monitoring of existing resources, use the [Reports](/guide/reports-insights/reports) page to generate compliance reports (CIS Benchmark, SOC2, HIPAA, etc.) that assess your deployed infrastructure against industry frameworks.
## Integration with Other Features
Security rules work alongside other CloudAgent capabilities:
- **Reports**: Compliance reports assess your deployed resources against similar standards. Security rules prevent new violations; reports catch existing ones.
- **Recommendations**: CloudAgent recommends enabling security services (GuardDuty, Security Hub) that complement your baseline rules.
- **Blueprints**: When agents generate infrastructure, security rules are applied automatically to the output template.
- **Governance**: Required tags and change approvals complement security rules — together they form a complete compliance framework.
## Troubleshooting
**Deployment blocked unexpectedly**: Check which rule failed in the deployment preview. If the rule doesn't apply to your use case, disable it in the workload's Security Rules tab and redeploy.
**Too many rules enabled**: Start with a preset that matches your environment (e.g., "Development" for staging) and add rules incrementally rather than starting with "All Best Practices."
**Rule changes not taking effect**: Ensure you clicked Save after modifying rules. Rule changes are stored with the workload and apply to the next deployment.
**Cannot find a specific rule**: Use the "Group by Service" view and expand the relevant AWS service to locate rules for that service.
## Next Steps
- [Governance & Architecture](/guide/workloads-governance/governance) — Configure change approvals, required tags, and architecture preferences
- [Managing Workloads](/guide/workloads-governance/workloads) — Set up workloads and assign security baselines
- [Reports](/guide/reports-insights/reports) — Run compliance reports to assess existing infrastructure
- [Recommendations](/guide/reports-insights/recommendations) — Review security recommendations across your environment
# Governance & Architecture
# Governance & Architecture
## What Is Governance in CloudAgent?
Governance in CloudAgent provides organizational controls for how infrastructure is deployed and managed. While [Security Rules](/guide/workloads-governance/security-baselines) enforce technical compliance (encryption, public access, etc.), governance controls enforce operational standards — change approvals, tagging policies, architecture preferences, and deployment methods.
These settings are configured per workload and are applied automatically when developers request infrastructure through CloudAgent's MCP integration or blueprint system.
## Accessing Governance Settings
Navigate to any workload and you'll find governance settings across three tabs:
1. **Governance** — Change approvals and required tags
2. **Architecture** — Infrastructure preferences and patterns
3. **Deployment Settings** — IaC method, CI/CD, and networking
## Change Approvals
Control whether infrastructure changes are deployed immediately or require review.
### Deployment Modes
| Mode | Behavior |
|------|----------|
| Deploy immediately | Changes are applied to AWS without a review step (default) |
| Create change set for review | A CloudFormation change set is created and held for manual approval |
When change set mode is enabled, you can configure notifications:
- **Email notifications**: Add one or more email addresses (comma-separated) to receive alerts when a change set is ready for review
- **Slack notifications**: Coming soon
> **Note:**
**Tip**: Use change set mode for production workloads so that all infrastructure changes go through a review step before reaching AWS.
## Required Resource Tags
Enforce consistent tagging standards across all resources deployed under a workload. Tags are automatically injected into generated templates.
For each required tag, configure:
| Field | Description |
|-------|-------------|
| Key | The tag name (e.g., "Environment", "CostCenter", "Owner") |
| Value | An optional fixed value — if set, this exact value is applied to all resources |
| Notes | Optional context for your team (e.g., "Required for EC2 instances") |
Common tagging patterns include environment labels ("prod", "staging", "dev"), cost center codes for chargeback, team ownership, and project identifiers.
## Architecture Preferences
Architecture preferences guide CloudAgent when generating infrastructure blueprints. These are soft preferences (not hard constraints) — they tell the system which cloud services and patterns to prefer when there are multiple valid options. The options below currently apply to AWS deployments.
### Compute
| Setting | Options |
|---------|---------|
| Instance Size | No Preference, Small, Large |
### Databases
| Setting | Options |
|---------|---------|
| SQL Database | No Preference, Aurora, MySQL, Postgres |
| NoSQL Database | No Preference, DynamoDB, RDS MongoDB |
### Website Hosting
| Setting | Options |
|---------|---------|
| Static Websites | No Preference, CloudFront + S3, Amplify |
| Dynamic Websites | No Preference, ECS + ALB, EC2 + ALB |
### Architecture Presets
For quick setup, apply a preset:
- **Production App/Environment**: Selects highly available patterns (Aurora, ECS + ALB, larger instances)
- **Sandbox/Testing**: Selects cost-efficient patterns (smaller instances, simpler hosting)
> **Note:**
Architecture preferences are applied when developers request infrastructure through MCP or when an agent generates a blueprint. The agent uses these preferences to select appropriate resource types and configurations.
## Deployment Settings
Configure how infrastructure is deployed to your cloud provider. The options below apply to AWS deployments; additional provider-specific methods will be available as CloudAgent expands its multi-cloud deployment support.
### Deployment Method
| Method | Description |
|--------|-------------|
| CloudFormation | AWS-native Infrastructure as Code (default) |
| Terraform | HashiCorp's cross-cloud IaC tool |
| OpenTofu | Open-source Terraform alternative |
| AWS CLI | Direct API calls for simple operations |
### Source Code Integration
Connect a GitHub repository to store and version your infrastructure code:
1. Select a GitHub connection (configured in [Integrations](/integrations))
2. Choose the repository and branch
3. Infrastructure templates are committed to the repo on each deployment
If you prefer not to use source control, select "No source code" — templates are managed within CloudAgent.
### Deployment Flow
| Flow | Behavior |
|------|----------|
| Manual | Developer initiates each deployment through CloudAgent |
| GitHub Actions | Deployment triggers automatically on code push |
| CodePipeline/CodeBuild | AWS-native CI/CD pipeline handles deployment |
For automated flows, you can configure:
- **Automatic deployment**: Deploy when changes land on the configured branch
- **Require approval step**: Pause the pipeline for manual review before deployment
- **Branch selection**: Choose which branch triggers deployments
### Terraform State Management
When using Terraform or OpenTofu, configure where state is stored:
- **Not set**: State managed locally (not recommended for teams)
- **S3 bucket**: Specify a bucket name for remote state storage
### Networking
- **Use existing VPCs**: Enable this to deploy into your existing VPC infrastructure instead of creating new VPCs. Specify VPC IDs or use the "Fetch VPCs" button to discover available VPCs in your account.
### Resource Type Controls
Restrict which AWS resource types can be deployed under this workload:
- **Allow All Resources**: Any resource type can be created
- **Allowed Resources List**: Only specified resource types are permitted
## How Governance Applies During Deployment
When a developer requests infrastructure through MCP or a blueprint, CloudAgent applies governance in this order:
1. **Architecture preferences** guide resource selection (e.g., Aurora over MySQL)
2. **Required tags** are injected into the generated template
3. **Security rules** validate the template for compliance
4. **Deployment method** determines how the template reaches AWS
5. **Change approval** controls whether deployment proceeds immediately or waits for review
If any step fails validation, the developer receives a clear explanation of what was blocked and why, along with a suggested fix.
## Troubleshooting
**Changes deploying without review**: Check that the Governance tab is set to "Create change set for review" rather than "Deploy immediately."
**Tags not appearing on resources**: Verify that required tags are saved in the Governance tab. Tags are applied at template generation time — existing resources won't retroactively receive tags.
**Architecture preferences not reflected**: Preferences are guidance, not constraints. If a specific resource type is explicitly requested, it may override the preference. Check the generated template to see what was applied.
**Cannot connect GitHub repository**: Ensure you have a GitHub integration configured in your account settings. The repository selector only shows repos from connected GitHub accounts.
## Next Steps
- [Security Rules & Baselines](/guide/workloads-governance/security-baselines) — Configure security compliance rules for your workload
- [Managing Workloads](/guide/workloads-governance/workloads) — Create and manage workload definitions
- [Blueprints & Agents](/guide/automation/blueprints) — Use agents to generate governed infrastructure
- [MCP Integration](/guide/mcp) — Connect your IDE for developer-driven infrastructure requests
# Reports & Insights
# Recommendations
# Recommendations
## Objective
Review and act on AI-powered recommendations to improve security, reduce costs, and optimize your cloud infrastructure.
The **Recommendations** page provides a centralized view of all findings and suggestions across your connected cloud environments.
## Accessing Recommendations
1. Navigate to **Recommendations** in the sidebar.
2. You will see a comprehensive list of all recommendations organized by category and priority.
> **Note:**
**Quick Access**: You can also access category-specific recommendations directly from the Dashboard's Smart Recommendations widget.
## Recommendation Categories
CloudAgent organizes recommendations into actionable categories:
### Critical Security
High-priority security issues that require immediate attention:
- Public S3 buckets
- Overly permissive IAM policies
- Unencrypted data stores
- Security group misconfigurations
### Cost Savings
Opportunities to reduce your cloud spend:
- Idle or underutilized resources
- Reserved instance recommendations
- Right-sizing suggestions
- Orphaned resources (unattached EBS volumes, unused Elastic IPs)
### Resource Cleanup
Identification of resources that can be removed:
- Unused security groups
- Stale snapshots
- Abandoned load balancers
- Empty S3 buckets
### Compliance
Audit items mapped to industry frameworks:
- SOC 2 requirements
- HIPAA controls
- CIS Benchmark findings
- PCI DSS compliance gaps
### Platform Insights
Suggestions to maximize your use of CloudAgent:
- Incomplete workload configurations
- Untracked resources
- Missing environment labels
### Operational Health
Findings from health analysis that point to availability, capacity, configuration, or runtime lifecycle issues:
- Failed or rolled-back CloudFormation stacks
- CloudFormation stack drift
- Database capacity pressure, replication lag, deadlocks, or log errors
- Runtime versions that are deprecated or nearing end of support
## Recommendation Details
Each recommendation includes:
| Field | Description |
|-------|-------------|
| **Priority** | Severity level (Critical, High, Medium, Low) |
| **Resources** | Number of affected resources |
| **Environment** | Which cloud environment contains the finding |
| **Updated** | When the recommendation was last refreshed |
## Taking Action
For each recommendation, you can:
1. **View Details**: Click to see the specific resources affected.
2. **Remediate**: Generate a blueprint to fix the issue automatically.
3. **Dismiss**: Mark as acknowledged if the finding is a known exception.
4. **Create Workflow**: Set up automated remediation for recurring issues.
> **Note:**
**Tip**: Address Critical and High priority recommendations within 24-48 hours to maintain a strong security posture.
Recommendations can be generated from stored scanner artifacts. If a health, cost, threat, or inventory scan is still running, related recommendations may update after the artifact becomes available.
## Filtering and Search
Use the filtering options to focus on specific findings:
- **By Priority**: Show only Critical, High, Medium, or Low items
- **By Category**: Filter by Security, Cost, Cleanup, or Compliance
- **By Environment**: Focus on a specific AWS account
- **By Workload**: View recommendations for a particular workload
## Next Steps
- [Artifact Analysis](/guide/reports-insights/artifact-analysis) — Understand how recommendations depend on stored scanner artifacts
- [Reports](/guide/reports-insights/reports) — Generate compliance reports based on recommendation findings
- [My Workflows](/guide/automation/workflows) — Automate remediation actions for recurring recommendations
- [Blueprints & Agents](/guide/automation/blueprints) — Use agents to execute remediation blueprints
# Reports
# Reports
## Objective
Generate and review compliance reports to assess your cloud security posture against industry frameworks.
CloudAgent provides detailed security and compliance reports that help you understand your environment's adherence to best practices and regulatory requirements.
## Accessing Reports
Reports can be accessed from multiple locations:
1. **Dashboard**: Quick access via the Reports widget
2. **Workload Details**: Reports specific to a workload in the Reports section
3. **Reports Page**: Navigate to **Reports** in the sidebar for the full report library
## Available Reports
CloudAgent offers a comprehensive library of compliance and security reports:
| Report | Category | Description |
|--------|----------|-------------|
| SOC2 Compliance Report | Security & Governance | Assesses environments against SOC2 categories like logical access, system operations, and confidentiality |
| PCI DSS 3.2.1 Compliance Report | Security & Governance | Evaluates Payment Card Industry Data Security Standard requirements |
| HIPAA Compliance Report | Security & Governance | Checks AWS configurations for HIPAA compliance across access, auditing, and encryption |
| CIS AWS Foundations Benchmark v3.0 | Security & Governance | Evaluates AWS configuration against Center for Internet Security benchmarks |
| NIST 800-53 v5 Compliance Report | Security & Governance | Assesses against NIST security and privacy controls |
| NIST 800-171 Compliance Report | Security & Governance | Validates controlled unclassified information (CUI) protection |
| NIST Cybersecurity Framework (CSF) Report | Security & Governance | Evaluates against the NIST CSF framework |
| ISO 27001 Annex A Compliance Report | Security & Governance | Checks against ISO 27001 information security controls |
| GDPR Compliance Report | Security & Governance | Reviews AWS practices against GDPR Articles 25, 30, and 32 |
| FedRAMP Low Compliance Report | Security & Governance | Validates AWS services against FedRAMP Low controls |
| FedRAMP Moderate Compliance Report | Security & Governance | Assesses environments for FedRAMP Moderate control coverage |
| Canada GC Compliance Report | Security & Governance | Evaluates against Canadian Guardrail controls for access, monitoring, and encryption |
| CMMC 2.0 Level 1 Compliance Report | Security & Governance | Checks basic safeguarding controls including access, authentication, and boundary protection |
| CMMC 2.0 Level 2 Compliance Report | Security & Governance | Evaluates advanced CMMC Level 2 controls across identity, configuration, and secure communications |
| RBI Cyber Security Framework Report | Security & Governance | Assesses against Reserve Bank of India cybersecurity guidelines |
| AWS Resiliency and High Availability Report | Resilience & Backup | Checks multi-AZ deployments, delete protection, and backup configurations |
| AWS Resource Backup Coverage Report | Resilience & Backup | Validates backup policies and coverage across resources |
| Unused AWS Resources Report | Cost & Billing | Identifies idle or unused resources for cost optimization |
| AWS Logging Status Report | Logging & Monitoring | Verifies CloudTrail, VPC Flow Logs, and other logging configurations |
| AWS Public Resource Exposure Report | Security & Governance | Scans for publicly accessible resources |
| AWS Encryption In-Transit Coverage Report | Security & Governance | Validates TLS/SSL configurations and encryption in transit |
For the complete and up-to-date list, visit [cloudagent.io/libraries/all-reports](https://cloudagent.io/libraries/all-reports).
## Report Status
Each report displays a status indicator:
| Status | Meaning |
|--------|---------|
| **Passed** | All checks passed successfully |
| **Warning** | Some non-critical findings require attention |
| **Failed** | Findings that need remediation |
| **Running** | Report generation in progress |
## Running a New Report
1. Navigate to the **Reports** page or workload details.
2. Click **+ Run New Report**.
3. Select the report type from the available options.
4. Choose the target environment(s).
5. Click **Generate** to start the report.
> **Note:**
**Processing Time**: Reports typically complete within 5-15 minutes depending on the size of your environment.
## Viewing Report Details
Click **View Report** on any completed report to see:
- **Executive Summary**: High-level overview of findings
- **Detailed Findings**: Individual check results with pass/fail status
- **Affected Resources**: Specific resources that need attention
- **Remediation Steps**: Recommended actions to resolve issues
- **Export Options**: Download as PDF for sharing with auditors
## Scheduling Reports
To run reports on a recurring schedule, create a workflow:
1. Navigate to **My Workflows**.
2. Click **+ Create Workflow**.
3. Select the report you want to schedule (e.g., "Canada GC Compliance Report").
4. Configure the schedule (Daily, Weekly, Monthly).
5. Save the workflow.
The report will run automatically at the scheduled time.
> **Note:**
**Notifications**: Configure email alerts in the workflow to receive reports automatically when they complete.
## Report History
All generated reports are stored in your report history:
- View past reports to track compliance trends
- Compare results over time
- Export historical data for audits
## Next Steps
- [My Workflows](/guide/automation/workflows) — Schedule automated report generation
- [Audit Logs](/guide/reports-insights/audit-logs) — Use report history as part of your audit trail
- [Recommendations](/guide/reports-insights/recommendations) — Act on findings surfaced in reports
# Executive Summaries
# Executive Summaries
## Objective
Generate concise, stakeholder-friendly summaries for cloud environments and workloads. Executive Summaries help teams understand current posture, key findings, and likely next actions without reading every underlying report.
## Accessing Executive Summaries
Navigate to **Executive Summaries** in the sidebar, or go directly to `/dashboard/executive-summaries`.
The page is split into two sections:
| Section | What It Covers |
|---------|----------------|
| Cloud Environments | Account- or environment-level summaries |
| Workloads | Application- or stack-level summaries |
## Environment vs Workload Summaries
### Environment Summaries
Environment summaries are best when you want an account-level view across recommendations, reports, and scanner results tied to one connected cloud environment.
Use them for:
- account health reviews
- leadership updates by environment
- compliance and operations check-ins
- pre-change or pre-remediation context
### Workload Summaries
Workload summaries focus on one application, platform, or stack and the resources CloudAgent tracks for it.
Use them for:
- service ownership reviews
- architecture and workload posture discussions
- release readiness or remediation planning
- sharing a concise status update with delivery teams
## What Data Feeds a Summary
Executive summaries are generated from the data CloudAgent already has for the selected environment or workload. Depending on what is available, a summary can draw from:
- reports and report summaries
- recommendations
- health analysis
- cost analysis
- workload context and tracked resources
The exact depth of the summary depends on how much current product data exists. A well-scoped environment or workload with recent reports and findings will produce a stronger summary than one with little recent activity.
## Viewing and Refreshing Summaries
Each card shows whether a summary already exists.
Typical actions:
1. open the summary to review it in detail
2. refresh the summary when the underlying product data changes
3. drill into the workload or supporting report for deeper evidence
If a summary is missing, generate it from the page before using it in stakeholder communication.
## Relationship to Reports and Recommendations
Executive summaries are not a replacement for reports or recommendations.
| Feature | Best For |
|---------|----------|
| Executive Summary | Fast briefing and decision support |
| Report | Detailed findings, framework mapping, and evidence |
| Recommendation | Actionable remediation or optimization items |
In practice:
- use a report when you need detailed controls or affected resources
- use recommendations when you need prioritized actions
- use an executive summary when you need the narrative roll-up
## Using Executive Summaries from Command Center
Command Center can preview executive summaries for environments and workloads. This is useful when:
- a user asks for a quick current-state briefing
- a recommendation needs business context before remediation
- an approval decision needs a concise summary rather than a full report review
When used in Command Center, keep the scope tight so the preview reflects the right environment, workload, or report context.
> **Note:**
Refresh an executive summary after major report runs, new recommendation cycles, or significant workload changes. Otherwise the summary may lag behind the current product state.
## Troubleshooting
**No summary is available**: Generate one from the page first.
**A summary feels outdated**: Refresh it after new reports, findings, or workload changes.
**A workload summary lacks detail**: Check whether the workload has recent reports, recommendations, and tracked resources.
**A summary mentions reports you cannot find**: Open the underlying workload or reports page to inspect the supporting source data.
## Next Steps
- [Command Center](/guide/dashboards/command-center) — Use executive summaries as part of guided review and approval flows
- [Reports](/guide/reports-insights/reports) — Inspect the underlying report evidence behind a summary
- [Managing Workloads](/guide/workloads-governance/workloads) — Improve workload context so summaries stay useful
# Artifact Analysis
# Artifact Analysis
## Objective
Understand how CloudAgent stores and reuses scanner results for health, cost, inventory, and threat analysis. This page explains why some dashboards show pending states and how workflows can analyze existing artifacts instead of starting a new report run every time.
## What an Artifact Is
When CloudAgent runs a scanner task, it writes the result as a stored artifact. That artifact becomes the source for downstream product views and automation.
Common artifact types include:
| Artifact Type | Used By |
|---------------|---------|
| Health | Health Dashboard, recommendations, workflows |
| Cost | Cost Dashboard, recommendations, workflows |
| Inventory | workload context, resource review, workflows |
| Threat | Threat analysis, recommendations, workflows |
This model lets CloudAgent reuse one scanner result in multiple places instead of repeating the same cloud API calls for every view.
## Why Results Can Be Pending
Scanner tasks run asynchronously. After a refresh or workflow step starts, there is often a delay before the artifact is available to load.
During that window, you may see:
- pending
- not ready
- running
- waiting for scanner output
This is normal. The product is waiting for the stored artifact to finish writing.
> **Note:**
A pending state does not always mean a failure. It often means the scanner task is still running or the artifact has not been indexed yet.
## Refresh Behavior
Most dashboards and workflows follow the same pattern:
1. start or request a scan
2. wait for the background task to write the artifact
3. load the stored artifact into the UI or workflow step
Depending on the feature, CloudAgent may reuse a recent artifact instead of generating a new one immediately. This reduces repeated cloud API calls and speeds up the user experience.
## How Artifacts Feed Dashboards
Stored artifacts are reused across product surfaces:
- **Health Dashboard** loads health artifacts for workloads and environments
- **Cost Dashboard** loads stored cost analysis after a refresh completes
- **Threat Management** uses stored threat artifacts where available
- **Recommendations** can update when new health, cost, inventory, or threat artifacts arrive
If a dashboard looks stale, confirm whether you are viewing a recent stored artifact or still waiting on a new scan to finish.
## How Artifacts Feed Recommendations
Recommendations can be generated or refreshed from the latest stored artifact. This is why recommendation changes may appear after a dashboard refresh completes instead of instantly.
Examples:
- a new health artifact can generate operational health recommendations
- a new cost artifact can update savings and cleanup findings
- a threat artifact can update threat posture recommendations
## How Workflows Use Existing Artifacts
Workflows can analyze stored artifacts without running a fresh report blueprint every time.
This is most visible in report tasks that use:
| Mode | Behavior |
|------|----------|
| `run_report` | Creates a new report or scan run |
| `analyze_existing` | Reads the latest stored artifact and summarizes it |
Use `analyze_existing` when you want a recurring workflow to summarize current posture or findings quickly. Use `run_report` when the workflow must generate new evidence first.
## Troubleshooting Pending or Missing Results
**A dashboard still says pending**: Wait for the background scan to complete, then refresh the page.
**Recommendations did not update yet**: The source artifact may still be running or may not have been refreshed yet.
**A workflow step did not continue**: Check whether it is waiting on a multi-environment scan or stored artifact before the next node can run.
**The wrong environment data is showing**: Confirm the selected permission profile or workload context. Artifact loading depends on the correct environment association.
## Next Steps
- [Health Dashboard](/guide/dashboards/health) — Review how health artifacts surface in the dashboard
- [Cost Dashboard](/guide/dashboards/cost) — Understand stored cost analysis and refresh behavior
- [Recommendations](/guide/reports-insights/recommendations) — See how artifact-backed findings appear as actions
- [My Workflows](/guide/automation/workflows) — Use `analyze_existing` in recurring workflows
# Audit Logs
# Audit Logs & Activity
## Overview
CloudAgent tracks the execution history of all automated actions — agent runs, workflow executions, report scans, and blueprint deployments. This activity trail serves as an audit log for understanding what CloudAgent has done in your environments, when it happened, and what the results were.
## Where to Find Activity History
Activity history is spread across three views, each accessible from the sidebar:
| View | What It Shows | Navigate To |
|------|-------------|------------|
| Agent History | All agent and blueprint executions with detailed logs | **Blueprints & Agents** → Agent History tab |
| Workflow History | All workflow runs with status and results | **My Workflows** → History |
| Report History | All compliance report and scan executions | **Reports** → My Reports |
## Agent History
The Agent History tab (under Blueprints & Agents) is the most comprehensive activity view. Every time an agent runs — whether triggered by a blueprint, a workflow, or a direct user action — it's logged here.
### What's Recorded
Each agent execution record includes:
| Field | Description |
|-------|-------------|
| Name | The agent or blueprint name |
| Environment | Which cloud account the agent operated on |
| Workflow | Link to the parent workflow, if the agent was triggered by one |
| Status | Current state: Running, Waiting on User, Completed, or Failed |
| Summary | AI-generated summary of what the agent did and found |
| Timestamp | When the execution started and last updated |
### Execution Details
Click any agent record to view the full execution log, which includes:
- **Step-by-step timeline**: Each action the agent took in sequence
- **Detailed logs**: Output from each operation
- **Resources modified**: What was created, updated, or deleted in your cloud account
- **Errors**: Any issues encountered during execution
### Search and Filter
Use the search bar to filter agent history by name, status, environment, or summary content. Results are sorted by most recent first, with the ability to load additional months of history.
> **Note:**
Agent executions include a human-in-the-loop checkpoint — agents pause before making state-changing operations in your cloud account, giving you a chance to review and approve before proceeding.
## Workflow History
The Workflow History view shows all workflow executions:
- **Workflow title** and configuration
- **Status**: Completed, Failed, Running
- **Last update** timestamp
- **Execution details**: Click to see the full workflow definition and results
Search and sort by title, status, or date. Load older history in 3-month increments.
## Report History
The Report History (My Reports) view tracks all compliance report and scan executions:
- **Report name** and type (e.g., SOC2, CIS Benchmark, HIPAA)
- **Cloud Environment** the report was run against
- **Parent workflow** if the report was triggered by a scheduled workflow
- **Status**: Complete, In Progress, or Failed
- **Actions**: View the full report, or open an AI chat to analyze findings
## Using Activity Data for Audits
CloudAgent's execution history provides evidence for compliance audits:
**What you can demonstrate:**
- When compliance reports were generated and what they found
- Which remediation actions were taken and by whom (user-initiated vs. automated)
- That human approval was required before state-changing operations
- The timeline of security improvements across your environment
**How to export evidence:**
- Open any completed report and export it as PDF for auditor review
- Screenshot agent execution timelines showing the sequence of actions taken
- Reference workflow schedules to demonstrate ongoing compliance monitoring cadence
> **Note:**
Schedule regular compliance reports (weekly or monthly) using [My Workflows](/guide/automation/workflows). This creates a consistent audit trail of compliance posture over time.
## Data Retention
Execution history is retained and available through the time-window pagination in each view. Load older records in 3-month increments to access historical data.
## Next Steps
- [Blueprints & Agents](/guide/automation/blueprints) — Understand how agents execute and generate logs
- [Reports](/guide/reports-insights/reports) — Run compliance reports that feed into your audit trail
- [My Workflows](/guide/automation/workflows) — Schedule automated checks for continuous compliance evidence
# Automation
# My Workflows
# My Workflows
## Objective
Create, manage, and monitor automated workflows that execute recurring cloud operations.
**My Workflows** allows you to automate repetitive tasks, schedule operations, and create multi-step processes that run without manual intervention.
## Accessing Workflows
Navigate to **My Workflows** in the sidebar to view and manage your automated tasks.
## Understanding Workflows
A workflow is an automated sequence of actions that can:
- Run on a schedule (daily, weekly, monthly)
- Execute multiple steps in order
- Pause for human approval when needed
- Notify you of results
## Workflow Types
### Manual Workflows
Triggered on-demand when you need them:
- One-time cleanup operations
- Ad-hoc security scans
- On-demand backups
### Scheduled Workflows
Run automatically at specified intervals:
- Daily backup verification
- Weekly compliance checks
- Monthly cost reports
### Event-Driven Workflows
Triggered by specific conditions:
- New resource detection
- Security finding alerts
- Threshold breaches
## Building a Workflow
CloudAgent workflows are built from connected nodes. A workflow can combine discovery, analysis, report generation, approvals, and remediation in one execution path.
### Common Node Types
| Node Type | Purpose | Typical Use |
|-----------|---------|-------------|
| Trigger | Starts the workflow manually or on a schedule | Weekly checks, monthly reports, on-demand runs |
| `cloudTask` | Runs an infrastructure or cloud action against one or more environments | Enable a service, run a scan, gather context |
| `reportTask` | Generates a report or analyzes existing stored artifacts | Compliance reports, cost summaries, health reviews |
| Approval / Decision | Pauses for review before continuing | Production changes, high-risk remediation |
| Notification / Follow-up | Sends results or continues with downstream actions | Notify a team, hand off to a blueprint, branch on outcome |
## Creating a Workflow
1. Navigate to **My Workflows**.
2. Click **+ Create Workflow**.
3. Choose a template or start from scratch.
4. Configure the workflow steps:
- **Action**: What the workflow should do
- **Target**: Which resources or environments
- **Schedule**: When it should run
- **Notifications**: Who to alert
5. Click **Save** to create the workflow.
> **Note:**
**Templates**: CloudAgent provides pre-built workflow templates for common operations like backup verification, security scanning, and cost optimization.
## Workflow Status
| Status | Description |
|--------|-------------|
| **Active** | Workflow is running on schedule |
| **Paused** | Temporarily disabled |
| **Waiting on User** | Requires your approval to continue |
| **Completed** | Finished execution successfully |
| **Failed** | Encountered an error |
| **Running** | Currently executing |
## Managing Workflows
### Pause a Workflow
Click the **Pause** button to temporarily stop a scheduled workflow without deleting it.
### Resume a Workflow
Click **Resume** to reactivate a paused workflow.
### Edit a Workflow
Click on the workflow name to modify its configuration, schedule, or steps.
### Delete a Workflow
Remove workflows you no longer need from the workflow list.
## Workflow Actions
Common actions available in workflows:
### Infrastructure Operations
- **Configure AWS Backup**: Set up backup policies for DynamoDB tables
- **Enable S3 Versioning**: Turn on versioning for S3 buckets
- **Update Security Groups**: Modify firewall rules
### Compliance and Security
- **Run CIS Benchmarks Report**: Generate compliance assessment
- **Scan for Public Access**: Check for publicly exposed resources
- **Audit IAM Permissions**: Review access policies
### Cost Management
- **Run Unused Resources Report**: Find idle resources
- **Check Reserved Instance Coverage**: Optimize RI utilization
- **Generate Cost Report**: Create spending analysis
### Artifact Analysis
- **Analyze Existing Cost Data**: Summarize spend trends from the latest cost artifact
- **Analyze Health Findings**: Group active health issues by service, region, severity, or workload
- **Analyze Inventory**: Count resources by service and region or identify risky resource concentrations
- **Analyze Threat Findings**: Summarize current threat findings and prioritize follow-up actions
Artifact analysis uses existing scanner results for cost, health, inventory, or threat data. Use it when you want a workflow to review data CloudAgent has already collected instead of running a new report blueprint first.
## Report Tasks
CloudAgent supports two common report-task modes:
| Mode | What It Does | Use When |
|------|--------------|----------|
| `run_report` | Runs a report blueprint and waits for the new result | You need a fresh compliance, security, or inventory report |
| `analyze_existing` | Reads a stored cost, health, inventory, or threat artifact and summarizes it | You want to review data CloudAgent already collected |
Use `run_report` when the workflow needs a new scan or formal report output. Use `analyze_existing` when the workflow should act on the latest available artifact without waiting for a new report blueprint to finish.
For more on how stored artifacts behave, see [Artifact Analysis](/guide/reports-insights/artifact-analysis).
## Multi-Environment Tasks
Workflow tasks can run against one environment or multiple selected environments. For multi-environment cloud and report tasks, CloudAgent controls how the next workflow step advances:
| Advance Mode | Behavior | Use When |
|--------------|----------|----------|
| Each | Downstream steps run separately as each environment finishes | You want per-environment branching, notifications, approvals, or follow-up actions |
| All | Downstream steps wait until every environment finishes | You want one combined summary, comparison, or decision after all environments complete |
For large environment selections, CloudAgent may split scanner work into multiple background tasks. The workflow still tracks the overall result and waits according to the selected advance mode.
This matters most when downstream steps depend on aggregated results. Use **Each** when a workflow should branch, notify, or request approval per environment. Use **All** when you need one roll-up view after every selected environment finishes.
## Human-in-the-Loop
For sensitive operations, workflows can pause and wait for approval:
1. Workflow reaches an approval step.
2. You receive a notification.
3. Review the proposed action in the dashboard.
4. Click **Continue** to proceed or **Cancel** to stop.
> **Note:**
**Tip**: Enable approval steps for any workflow that modifies production resources.
Approval steps are also useful for workflows that combine findings from multiple sources. A common pattern is:
1. Analyze health, cost, or threat artifacts
2. Generate a recommendation or report summary
3. Pause for approval
4. Run a remediation blueprint only after review
## Viewing Workflow History
Click on any workflow to see:
- **Execution History**: Past runs with timestamps
- **Step Details**: What happened at each step
- **Logs**: Detailed output from each action
- **Errors**: Any issues encountered during execution
Execution history is where you confirm whether a workflow is:
- waiting for user approval
- still processing a background scan
- blocked on an environment-specific branch
- complete for some environments but still running for others
## Integration with Blueprints
Workflows can execute blueprints as part of their steps:
1. Create a blueprint for the desired infrastructure change.
2. Add a "Run Blueprint" step to your workflow.
3. The blueprint deploys automatically when the workflow runs.
When a blueprint step follows another workflow step, CloudAgent can pass concrete upstream context into the blueprint run, such as resource IDs, ARNs, regions, or investigation targets. This helps downstream blueprint runs act on the exact resources found earlier in the workflow.
## Troubleshooting
**A workflow is stuck in pending or running**: Check whether the current step is waiting on a background scanner task to finish writing an artifact. Cost, health, inventory, and threat analysis can stay pending until the stored result is available.
**Downstream steps are not starting**: Confirm the selected advance mode. With `all`, downstream steps wait for every selected environment to finish.
**A report task did not produce a new report**: Make sure the task mode is correct. `analyze_existing` summarizes an existing artifact; it does not create a new report run.
**A remediation step does not have the right resource context**: Review the upstream step output and blueprint inputs. CloudAgent can pass resource IDs, ARNs, regions, and account context into later blueprint runs, but the blueprint still needs matching input fields or instructions.
## Next Steps
- [Blueprints & Agents](/guide/automation/blueprints) — Create reusable infrastructure templates
- [Reports](/guide/reports-insights/reports) — Generate compliance reports to use in workflows
- [Artifact Analysis](/guide/reports-insights/artifact-analysis) — Understand stored scan artifacts and pending states
- [Recommendations](/guide/reports-insights/recommendations) — View findings that can trigger workflow actions
# Blueprints & Agents
# Blueprints & Agents
## Objective
Design, visualize, and deploy standardized infrastructure templates across your environments.
The **Blueprint Builder** allows you to design and deploy infrastructure templates.
## AI-Assisted Builder
The Blueprint Builder uses an AI agent to help you design infrastructure templates. Instead of writing complex code from scratch, you describe what you want in plain English.
### How it Works
1. **Define Objective**: Start by describing your goal (e.g., "Create a highly available ECS cluster with an Application Load Balancer").
2. **Generate Skeleton**: The AI analyzes your request and proposes a "Skeleton Plan" broken down into phases:
* **Assessment**: Checks prerequisites and current state.
* **Configuration**: Defines the resources and settings.
* **Validation**: Ensures the design meets best practices.
3. **Refine and Customize**: Use the **Plan Builder Assistant** chat to refine tasks, add notes, or change deployment methods (CloudFormation or CLI).
4. **Finalize**: Once satisfied, the builder generates the executable blueprint.
### Key Capabilities
- **Chat Interface**: Interact with the AI to iterate on your design.
- **Phased Approach**: Structured plans ensure no steps are missed.
- **Permission Calculation**: Automatically identifies the IAM permissions required to deploy the blueprint.
- **Deployment Options**: Support for standard CloudFormation stacks or CLI-based deployments.
To access it:
1. Click on **Blueprints & Agents** in the left sidebar.
2. Click **Create Blueprint** to start a new design.
## Running a Blueprint
To execute an existing blueprint:
1. Navigate to **Blueprints & Agents** > **My Blueprints**.
2. Find the blueprint you want to run.
3. Click **Run Blueprint**.
4. Select the target environment.
5. Review the execution plan.
6. Click **Execute** to deploy.
> **Note:**
**Tip**: You can also run blueprints directly from recommendations by clicking the "Remediate" button.
## Running Blueprints in Workflows
When a workflow runs a blueprint after another step, CloudAgent includes the workflow context in the blueprint run. For example, a workflow can find unhealthy resources, then pass the affected resource IDs, ARNs, regions, or account context into a remediation blueprint.
Blueprint runtime inputs can include:
| Input Type | Use For |
|------------|---------|
| Default values | Structured fields such as resource IDs, ARNs, names, regions, dates, and account identifiers |
| Additional instructions | Narrative guidance, investigation scope, required lists, or constraints that do not map to a single blueprint field |
| Target environment | The selected permission profile and account for the run |
This context passing is most useful for follow-up, investigation, and remediation blueprints that should act on the exact objects found by earlier workflow steps.
## Agent History
The **Agent History** tab shows the status and results of all blueprint executions and agent activities.
### Viewing Agent History
1. Navigate to **Blueprints & Agents**.
2. Click on the **Agent History** tab.
3. View all past and current agent executions.
### Agent Status
Each agent execution displays:
| Status | Description |
|--------|-------------|
| **Completed** | Successfully finished all steps |
| **Running** | Currently executing |
| **Waiting on User** | Paused, awaiting your approval |
| **Failed** | Encountered an error |
### Agent Details
Click on any agent entry to view:
- **Execution Timeline**: Step-by-step progress
- **Logs**: Detailed output from each action
- **Resources Modified**: What was created, updated, or deleted
- **Errors**: Any issues encountered
### Managing Running Agents
For agents that are running or waiting:
- **Continue**: Resume execution after reviewing
- **Mark As Complete**: Manually mark as finished
- **View History**: See detailed execution logs
> **Note:**
**Human-in-the-Loop**: Agents will pause and request your approval before making state-changing operations in your AWS environment.
### Searching Agent History
Use the search bar to find specific executions:
- Search by blueprint name
- Filter by status
- Filter by date range
## Next Steps
- [My Workflows](/guide/automation/workflows) — Automate blueprint execution on a schedule
- [AI Assistant](/guide/automation/assistant) — Use natural language to create and run blueprints
- [Recommendations](/guide/reports-insights/recommendations) — View findings that blueprints can remediate
# AI Assistant
# CloudAgent Assistant
The **CloudAgent Assistant** is an AI-powered companion designed to help you manage your cloud infrastructure using natural language. It lives in the bottom-right corner of the application and is always ready to assist.
## Overview
The Assistant is capable of performing complex operations by connecting directly to your cloud environment and the CloudAgent backend. It translates your English requests into specific actions, such as running AWS CLI commands, deploying CloudFormation stacks, or managing your workloads.
> **Note:**
**Tip**: You can ask the Assistant to "explain" resources or errors to get context-aware answers.
## Capabilities
The Assistant is equipped with a powerful set of tools that allow it to:
### 1. AWS Discovery and Inspection
You can ask the Assistant to inspect your live AWS environment. It uses read-only AWS CLI commands to fetch real-time data.
* **"List all EC2 instances in us-east-1."**
* **"Describe the security group 'sg-12345'."**
* **"Check if I have any S3 buckets with public access."**
### 2. Workload Management
The Assistant can view and update your CloudAgent workloads directly.
* **"List my workloads."**
* **"Update the 'payments' workload to use the 'prod' environment."**
* **"Add a rule to the 'portal' workload to prevent public S3 buckets."**
### 3. Infrastructure Deployment
You can deploy or update infrastructure using CloudFormation. The Assistant will always ask for your approval before making changes.
* **"Deploy a new S3 bucket named 'my-app-logs'."**
* **"Update the 'payments-stack' to enable versioning."**
* **"Create a standard VPC with 2 AZs."** (Uses built-in architecture templates)
### 4. Research and Validation
The Assistant has access to the web to research best practices, validate syntax, and find solutions to errors.
* **"How do I configure an ALB for gRPC?"**
* **"Find the CloudFormation syntax for an ECS Fargate service."**
* **"What does this error message mean?"**
## How to Use
1. Click the **CloudAgent** button in the bottom-right corner.
2. Type your request in plain English.
3. The Assistant will analyze your request and may:
* Ask clarifying questions.
* Run a read-only command to gather context.
* Propose a plan of action (e.g., a CloudFormation template).
4. **Review and Approve**: For any action that modifies your infrastructure, the Assistant will present a plan. You must approve it before execution proceeds.
## Safety and Security
* **Read-Only by Default**: The Assistant defaults to read-only actions for discovery.
* **Human-in-the-Loop**: All state-changing operations (Create, Update, Delete) require explicit user confirmation.
* **Guardrails**: Deployments are checked against your organization's security rules and policies.
## Next Steps
- [Blueprints & Agents](/guide/automation/blueprints) — Create reusable templates for common tasks
- [MCP Integration](/guide/mcp) — Connect CloudAgent to your IDE for AI-powered workflows
- [Managing Workloads](/guide/workloads-governance/workloads) — Configure the workloads the assistant can operate on
# MCP Integration
# MCP Integration
## Objective
Connect your AI tools to CloudAgent using the Model Context Protocol (MCP) to build and deploy cloud infrastructure with built-in guardrails.
> **Note:**
**What is MCP?** The Model Context Protocol is an open standard that allows AI-powered tools to connect to external services. CloudAgent's MCP server lets your AI assistant deploy infrastructure on your behalf, with security and governance controls applied automatically.
## Prerequisites
Before setting up MCP, ensure you have:
- A CloudAgent account with at least one [connected AWS environment](/guide/cloud-setup/aws)
- A workload configured with your team's security baselines and governance rules
- One of the supported AI tools: Cursor, Claude Desktop, or ChatGPT Desktop
## Step 1: Get Your MCP Configuration
1. Log in to [CloudAgent](https://cloudagent.io).
2. Navigate to **Setup** → **MCP Extension** in the sidebar.
3. Copy the configuration using **Copy Configuration** or download it with **Download Config**.
The configuration file looks like this:
```json
{
"mcpServers": {
"cloudagent": {
"url": "https://api.cloudagent.io/mcp",
"enabled": true
}
}
}
```
## Step 2: Configure Your AI Tool
Select your tool and follow the setup instructions: