Logging AWS Security Agent API calls with AWS CloudTrail Monitoring AWS Security Agent with Amazon CloudWatch Monitoring with Amazon EventBridge

Logging and monitoring in AWS Security Agent

Monitoring is an important part of maintaining the reliability, availability, and performance of AWS Security Agent and your other AWS solutions. AWS provides the following monitoring tools to watch AWS Security Agent, report when something is wrong, and take automatic actions when appropriate:

AWS CloudTrail captures API calls and related events made by or on behalf of your AWS account and delivers the log files to an Amazon S3 bucket that you specify. You can identify which users and accounts called AWS, the source IP address from which the calls were made, and when the calls occurred. For more information, see the AWS CloudTrail User Guide.
Amazon CloudWatch monitors your AWS resources and the applications you run on AWS in real time. You can collect and track metrics, create customized dashboards, and set alarms that notify you or take actions when a specified metric reaches a threshold that you specify. For more information, see the Amazon CloudWatch User Guide.
Amazon EventBridge is a serverless event bus service that makes it easy to connect your applications with data from a variety of sources. EventBridge delivers a stream of real-time data from your own applications, Software-as-a-Service (SaaS) applications, and AWS services and routes that data to targets. For more information, see the Amazon EventBridge User Guide.

Logging AWS Security Agent API calls with AWS CloudTrail

AWS Security Agent is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in AWS Security Agent. CloudTrail captures all API calls for AWS Security Agent as events. The calls captured include calls from the AWS Security Agent console and code calls to the AWS Security Agent API operations. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for AWS Security Agent. If you don’t configure a trail, you can still view the most recent events in the CloudTrail console in Event history. Using the information collected by CloudTrail, you can determine the request that was made to AWS Security Agent, the IP address from which the request was made, who made the request, when it was made, and additional details.

To learn more about CloudTrail, see the AWS CloudTrail User Guide.

AWS Security Agent information in CloudTrail

CloudTrail is enabled on your AWS account when you create the account. When activity occurs in AWS Security Agent, that activity is recorded in a CloudTrail event along with other AWS service events in Event history. You can view, search, and download recent events in your AWS account. For more information, see Viewing events with CloudTrail Event history.

For an ongoing record of events in your AWS account, including events for AWS Security Agent, create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see the following:

All AWS Security Agent actions are logged by CloudTrail and are documented in the AWS Security Agent API Reference. For example, calls to the CreatePentest, StartPentestExecution, and ListFindings actions generate entries in the CloudTrail log files.

Every event or log entry contains information about who generated the request. The identity information helps you determine the following:

Whether the request was made with root or AWS Identity and Access Management (IAM) user credentials.
Whether the request was made with temporary security credentials for a role or federated user.
Whether the request was made by another AWS service.

For more information, see the CloudTrail userIdentity element.

Understanding AWS Security Agent log file entries

A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files aren’t an ordered stack trace of the public API calls, so they don’t appear in any specific order.

The following example shows a CloudTrail log entry that demonstrates the CreatePentest action:


{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "IAMUser",
        "principalId": "AIDACKCEVSQ6C2EXAMPLE",
        "arn": "arn:aws:iam::123456789012:user/Alice",
        "accountId": "123456789012",
        "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
        "userName": "Alice"
    },
    "eventTime": "2025-01-15T10:30:00Z",
    "eventSource": "securityagent.amazonaws.com",
    "eventName": "CreatePentest",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "203.0.113.12",
    "userAgent": "aws-cli/2.13.0",
    "requestParameters": {
        "pentestName": "WebApp-Security-Test",
        "targetUrl": "https://example.com",
        "testScope": "OWASP-Top-10"
    },
    "responseElements": {
        "pentestId": "pt-1234567890abcdef0",
        "pentestArn": "arn:aws:securityagent:us-east-1:123456789012:pentest/pt-1234567890abcdef0"
    },
    "requestID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventID": "12345678-1234-1234-1234-123456789012",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management"
}

The following example shows a CloudTrail log entry that demonstrates the StartPentestExecution action:


{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "AROAEXAMPLEID:session-name",
        "arn": "arn:aws:sts::123456789012:assumed-role/SecurityTeamRole/session-name",
        "accountId": "123456789012",
        "accessKeyId": "ASIAIOSFODNN7EXAMPLE",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "AROAEXAMPLEID",
                "arn": "arn:aws:iam::123456789012:role/SecurityTeamRole",
                "accountId": "123456789012",
                "userName": "SecurityTeamRole"
            },
            "attributes": {
                "creationDate": "2025-01-15T09:00:00Z",
                "mfaAuthenticated": "true"
            }
        }
    },
    "eventTime": "2025-01-15T11:00:00Z",
    "eventSource": "securityagent.amazonaws.com",
    "eventName": "StartPentestExecution",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "203.0.113.45",
    "userAgent": "console.amazonaws.com",
    "requestParameters": {
        "pentestId": "pt-1234567890abcdef0"
    },
    "responseElements": {
        "executionId": "exec-abcdef1234567890",
        "status": "RUNNING"
    },
    "requestID": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "eventID": "23456789-2345-2345-2345-234567890123",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management"
}

Monitoring AWS Security Agent with Amazon CloudWatch

You can monitor AWS Security Agent using CloudWatch, which collects raw data and processes it into readable, near real-time metrics. These statistics are kept for 15 months, so that you can access historical information and gain a better perspective on how your security testing is performing. You can also set alarms that watch for certain thresholds, and send notifications or take actions when those thresholds are met.

AWS Security Agent metrics

AWS Security Agent sends the following metrics to CloudWatch:

Metric	Description	Unit
`PentestExecutions`	The number of penetration test executions started	Count
`PentestExecutionDuration`	The duration of penetration test executions	Seconds
`FindingsGenerated`	The number of security findings generated	Count
`CriticalFindings`	The number of critical severity findings	Count
`HighFindings`	The number of high severity findings	Count
`MediumFindings`	The number of medium severity findings	Count
`LowFindings`	The number of low severity findings	Count
`CodeReviews`	The number of code reviews performed	Count
`DesignReviews`	The number of design reviews performed	Count

Dimensions for AWS Security Agent metrics

AWS Security Agent metrics use the following dimensions:

Dimension	Description
`PentestId`	Filters metrics by specific penetration test
`ExecutionId`	Filters metrics by specific test execution
`Severity`	Filters findings metrics by severity level (Critical, High, Medium, Low)
`FindingType`	Filters metrics by type of security finding

Creating CloudWatch alarms for AWS Security Agent

You can create a CloudWatch alarm that sends an Amazon SNS message when the alarm changes state. An alarm watches a single metric over a time period you specify, and performs one or more actions based on the value of the metric relative to a given threshold over a number of time periods.

For example, you can create an alarm that monitors the number of critical findings and sends a notification when the number exceeds a threshold:

Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
In the navigation pane, choose Alarms, All alarms.
Choose Create alarm.
Choose Select metric.
Choose SecurityAgent, then choose the metric category you want to monitor.
Select the metric you want to monitor, then choose Select metric.
Configure the alarm conditions, notification, and other settings.
Choose Create alarm.

Monitoring with Amazon EventBridge

Amazon EventBridge enables you to automate your AWS services and respond automatically to system events such as application availability issues or resource changes. Events from AWS services are delivered to EventBridge in near real time. You can write simple rules to indicate which events are of interest to you, and what automated actions to take when an event matches a rule.

AWS Security Agent sends events to EventBridge when:

A penetration test execution completes
Critical or high severity findings are discovered
A code review or design review completes
A security requirement is violated

AWS Security Agent event examples

The following example shows an event that AWS Security Agent sends to EventBridge when a penetration test execution completes:


{
    "version": "0",
    "id": "12345678-1234-1234-1234-123456789012",
    "detail-type": "Security Agent Pentest Execution Status Change",
    "source": "aws.securityagent",
    "account": "123456789012",
    "time": "2025-01-15T12:00:00Z",
    "region": "us-east-1",
    "resources": [
        "arn:aws:securityagent:us-east-1:123456789012:pentest/pt-1234567890abcdef0"
    ],
    "detail": {
        "pentestId": "pt-1234567890abcdef0",
        "executionId": "exec-abcdef1234567890",
        "status": "COMPLETED",
        "findingsCount": 15,
        "criticalFindings": 2,
        "highFindings": 5,
        "mediumFindings": 6,
        "lowFindings": 2,
        "startTime": "2025-01-15T11:00:00Z",
        "endTime": "2025-01-15T12:00:00Z"
    }
}

The following example shows an event that AWS Security Agent sends when critical findings are discovered:


{
    "version": "0",
    "id": "23456789-2345-2345-2345-234567890123",
    "detail-type": "Security Agent Critical Finding Detected",
    "source": "aws.securityagent",
    "account": "123456789012",
    "time": "2025-01-15T11:30:00Z",
    "region": "us-east-1",
    "resources": [
        "arn:aws:securityagent:us-east-1:123456789012:finding/finding-1234567890"
    ],
    "detail": {
        "findingId": "finding-1234567890",
        "severity": "CRITICAL",
        "title": "SQL Injection Vulnerability Detected",
        "description": "A SQL injection vulnerability was found in the login endpoint",
        "affectedResource": "https://example.com/api/login",
        "pentestId": "pt-1234567890abcdef0",
        "executionId": "exec-abcdef1234567890",
        "detectionTime": "2025-01-15T11:30:00Z"
    }
}

Creating EventBridge rules for AWS Security Agent

You can create EventBridge rules to automatically respond to AWS Security Agent events. For example, you can create a rule that sends a notification to your security team when critical findings are detected.

To create an EventBridge rule:

Open the EventBridge console at https://console.aws.amazon.com/events/.
In the navigation pane, choose Rules.
Choose Create rule.
Enter a name and description for the rule.
For Event bus, choose default.
For Rule type, choose Rule with an event pattern.
Choose Next.
For Event source, choose AWS events or EventBridge partner events.
For Event pattern, choose Custom pattern and enter your event pattern.
Choose Next.
Select a target for the rule (such as an SNS topic or Lambda function).
Choose Next.
Review the rule configuration and choose Create rule.

Example event pattern to match critical findings:


{
    "source": ["aws.securityagent"],
    "detail-type": ["Security Agent Critical Finding Detected"],
    "detail": {
        "severity": ["CRITICAL"]
    }
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

IAM actions and resources migration

Logging with CloudTrail