Skip to content
This repository has been archived by the owner on May 10, 2024. It is now read-only.

Commit

Permalink
Update to latest AWS CloudTrail API
Browse files Browse the repository at this point in the history
  • Loading branch information
@danielgtaylor
danielgtaylor committed Dec 19, 2013
1 parent dcf3cbd commit aeafe9b
Showing 1 changed file with 161 additions and 112 deletions.
273 changes: 161 additions & 112 deletions boto/cloudtrail/layer1.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@ class CloudTrailConnection(AWSQueryConnection):
CloudTrail is a web service that records AWS API calls for your
AWS account and delivers log files to an Amazon S3 bucket. The
recorded information includes the identity of the user, the start
time of the event, the source IP address, the request parameters,
and the response elements returned by the service.
time of the AWS API call, the source IP address, the request
parameters, and the response elements returned by the service.
As an alternative to using the API, you can use one of the AWS
SDKs, which consist of libraries and sample code for various
Expand All @@ -52,11 +52,11 @@ class CloudTrailConnection(AWSQueryConnection):
programmatic access to AWSCloudTrail. For example, the SDKs take
care of cryptographically signing requests, managing errors, and
retrying requests automatically. For information about the AWS
SDKs, including how to download and install them, see the Tools
for Amazon Web Services page.
SDKs, including how to download and install them, see the `Tools
for Amazon Web Services page`_.
See the CloudTrail User Guide for information about the data that
is included with each event listed in the log files.
is included with each AWS API call listed in the log files.
"""
APIVersion = "2013-11-01"
DefaultRegionName = "us-east-1"
Expand All @@ -71,10 +71,9 @@ class CloudTrailConnection(AWSQueryConnection):
"TrailAlreadyExistsException": exceptions.TrailAlreadyExistsException,
"InsufficientSnsTopicPolicyException": exceptions.InsufficientSnsTopicPolicyException,
"InvalidTrailNameException": exceptions.InvalidTrailNameException,
"InternalErrorException": exceptions.InternalErrorException,
"TrailNotProvidedException": exceptions.TrailNotProvidedException,
"TrailNotFoundException": exceptions.TrailNotFoundException,
"S3BucketDoesNotExistException": exceptions.S3BucketDoesNotExistException,
"TrailNotProvidedException": exceptions.TrailNotProvidedException,
"InvalidS3PrefixException": exceptions.InvalidS3PrefixException,
"MaximumNumberOfTrailsExceededException": exceptions.MaximumNumberOfTrailsExceededException,
"InsufficientS3BucketPolicyException": exceptions.InsufficientS3BucketPolicyException,
Expand All @@ -96,89 +95,83 @@ def __init__(self, **kwargs):
def _required_auth_capability(self):
return ['hmac-v4']

def create_trail(self, trail=None):
def create_trail(self, name=None, s3_bucket_name=None,
s3_key_prefix=None, sns_topic_name=None,
include_global_service_events=None, trail=None):
"""
From the command line, use create-subscription.
From the command line, use `create-subscription`.
Creates a trail that specifies the settings for delivery of
log data to an Amazon S3 bucket. The request includes a Trail
structure that specifies the following:
+ Trail name.
+ The name of the Amazon S3 bucket to which CloudTrail
delivers your log files.
+ The name of the Amazon S3 key prefix that precedes each log
file.
+ The name of the Amazon SNS topic that notifies you that a
new file is available in your bucket.
+ Whether the log file should include events from global
services. Currently, the only events included in CloudTrail
log files are from IAM and AWS STS.
Returns the appropriate HTTP status code if successful. If
not, it returns either one of the CommonErrors or a
FrontEndException with one of the following error codes:
**MaximumNumberOfTrailsExceeded**
An attempt was made to create more trails than allowed. You
can only create one trail for each account in each region.
**TrailAlreadyExists**
log data to an Amazon S3 bucket.
An attempt was made to create a trail with a name that already
exists.
Support for passing Trail as a parameter ends as early as
February 25, 2014. The request and response examples in this
topic show the use of parameters as well as a Trail object.
Until Trail is removed, you can use either Trail or the
parameter list.
**S3BucketDoesNotExist**
Specified Amazon S3 bucket does not exist.
:type name: string
:param name: Specifies the name of the trail.
**InsufficientS3BucketPolicy**
:type s3_bucket_name: string
:param s3_bucket_name: Specifies the name of the Amazon S3 bucket
designated for publishing log files.
Policy on Amazon S3 bucket does not permit CloudTrail to write
to your bucket. See the AWS CloudTrail User Guide for the
required bucket policy.
:type s3_key_prefix: string
:param s3_key_prefix: Specifies the Amazon S3 key prefix that precedes
the name of the bucket you have designated for log file delivery.
**InsufficientSnsTopicPolicy**
:type sns_topic_name: string
:param sns_topic_name: Specifies the name of the Amazon SNS topic
defined for notification of log file delivery.
The policy on Amazon SNS topic does not permit CloudTrail to
write to it. Can also occur when an Amazon SNS topic does not
exist.
:type include_global_service_events: boolean
:param include_global_service_events: Specifies whether the trail is
publishing events from global services such as IAM to the log
files.
:type trail: dict
:param trail: Contains the Trail structure that specifies the settings
for each trail.
:param trail: Support for passing a Trail object in the CreateTrail or
UpdateTrail actions will end as early as February 15, 2014. Instead
of the Trail object and its members, use the parameters listed for
these actions.
"""
params = {}
if name is not None:
params['Name'] = name
if s3_bucket_name is not None:
params['S3BucketName'] = s3_bucket_name
if s3_key_prefix is not None:
params['S3KeyPrefix'] = s3_key_prefix
if sns_topic_name is not None:
params['SnsTopicName'] = sns_topic_name
if include_global_service_events is not None:
params['IncludeGlobalServiceEvents'] = include_global_service_events
if trail is not None:
params['trail'] = trail
return self.make_request(action='CreateTrail',
body=json.dumps(params))

def delete_trail(self, name=None):
def delete_trail(self, name):
"""
Deletes a trail.
:type name: string
:param name: The name of a trail to be deleted.
"""
params = {}
if name is not None:
params['Name'] = name
params = {'Name': name, }
return self.make_request(action='DeleteTrail',
body=json.dumps(params))

def describe_trails(self, trail_name_list=None):
"""
Retrieves the settings for some or all trails associated with
an account. Returns a list of Trail structures in JSON format.
an account.
:type trail_name_list: list
:param trail_name_list: The list of Trail object names.
:param trail_name_list: The list of trails.
"""
params = {}
Expand All @@ -187,97 +180,153 @@ def describe_trails(self, trail_name_list=None):
return self.make_request(action='DescribeTrails',
body=json.dumps(params))

def get_trail_status(self, name=None):
def get_trail_status(self, name):
"""
Returns GetTrailStatusResult, which contains a JSON-formatted
list of information about the trail specified in the request.
JSON fields include information such as delivery errors,
Amazon SNS and Amazon S3 errors, and times that logging
started and stopped for each trail.
Returns a JSON-formatted list of information about the
specified trail. Fields include information on delivery
errors, Amazon SNS and Amazon S3 errors, and start and stop
logging times for each trail.
The CloudTrail API is currently undergoing revision. This
action currently returns both new fields and fields slated for
removal from the API. The following lists indicate the plans
for each field:
**List of Members Planned for Ongoing Support**
+ IsLogging
+ LatestDeliveryTime
+ LatestNotificationTime
+ StartLoggingTime
+ StopLoggingTime
+ LatestNotificationError
+ LatestDeliveryError
**List of Members Scheduled for Removal**
+ **LatestDeliveryAttemptTime**: Use LatestDeliveryTime
instead.
+ **LatestNotificationAttemptTime**: Use
LatestNotificationTime instead.
+ **LatestDeliveryAttemptSucceeded**: No replacement. See the
note following this list.
+ **LatestNotificationAttemptSucceeded**: No replacement. See
the note following this list.
+ **TimeLoggingStarted**: Use StartLoggingTime instead.
+ **TimeLoggingStopped**: Use StopLoggingtime instead.
No replacements have been created for
LatestDeliveryAttemptSucceeded and
LatestNotificationAttemptSucceeded . Use LatestDeliveryError
and LatestNotificationError to evaluate success or failure of
log delivery or notification. Empty values returned for these
fields indicate success. An error in LatestDeliveryError
generally indicates either a missing bucket or insufficient
permissions to write to the bucket. Similarly, an error in
LatestNotificationError indicates either a missing topic or
insufficient permissions.
:type name: string
:param name: The name of the trail for which you are requesting the
current status.
"""
params = {}
if name is not None:
params['Name'] = name
params = {'Name': name, }
return self.make_request(action='GetTrailStatus',
body=json.dumps(params))

def start_logging(self, name=None):
def start_logging(self, name):
"""
Starts the processing of recording user activity events and
log file delivery for a trail.
Starts the recording of AWS API calls and log file delivery
for a trail.
:type name: string
:param name: The name of the Trail for which CloudTrail logs events.
:param name: The name of the trail for which CloudTrail logs AWS API
calls.
"""
params = {}
if name is not None:
params['Name'] = name
params = {'Name': name, }
return self.make_request(action='StartLogging',
body=json.dumps(params))

def stop_logging(self, name=None):
def stop_logging(self, name):
"""
Suspends the recording of user activity events and log file
delivery for the specified trail. Under most circumstances,
there is no need to use this action. You can update a trail
without stopping it first. This action is the only way to stop
logging activity.
Suspends the recording of AWS API calls and log file delivery
for the specified trail. Under most circumstances, there is no
need to use this action. You can update a trail without
stopping it first. This action is the only way to stop
recording.
:type name: string
:param name: Communicates to CloudTrail the name of the Trail for which
to stop logging events.
:param name: Communicates to CloudTrail the name of the trail for which
to stop logging AWS API calls.
"""
params = {}
if name is not None:
params['Name'] = name
params = {'Name': name, }
return self.make_request(action='StopLogging',
body=json.dumps(params))

def update_trail(self, trail=None):
def update_trail(self, name=None, s3_bucket_name=None,
s3_key_prefix=None, sns_topic_name=None,
include_global_service_events=None, trail=None):
"""
From the command line, use update-subscription.
From the command line, use `update-subscription`.
Updates the settings that specify delivery of log files.
Changes to a trail do not require stopping the CloudTrail
service. You can use this action to designate an existing
bucket for log delivery, or to create a new bucket and prefix.
If the existing bucket has previously been a target for
CloudTrail log files, an IAM policy exists for the bucket. If
you create a new bucket using UpdateTrail, you need to apply
the policy to the bucket using one of the means provided by
the Amazon S3 service.
The request includes a Trail structure that specifies the
following:
+ Trail name.
+ The name of the Amazon S3 bucket to which CloudTrail
delivers your log files.
+ The name of the Amazon S3 key prefix that precedes each log
file.
+ The name of the Amazon SNS topic that notifies you that a
new file is available in your bucket.
+ Whether the log file should include events from global
services, such as IAM or AWS STS.
**CreateTrail** returns the appropriate HTTP status code if
successful. If not, it returns either one of the common errors
or one of the exceptions listed at the end of this page.
service. Use this action to designate an existing bucket for
log delivery. If the existing bucket has previously been a
target for CloudTrail log files, an IAM policy exists for the
bucket.
Support for passing Trail as a parameter ends as early as
February 25, 2014. The request and response examples in this
topic show the use of parameters as well as a Trail object.
Until Trail is removed, you can use either Trail or the
parameter list.
:type name: string
:param name: Specifies the name of the trail.
:type s3_bucket_name: string
:param s3_bucket_name: Specifies the name of the Amazon S3 bucket
designated for publishing log files.
:type s3_key_prefix: string
:param s3_key_prefix: Specifies the Amazon S3 key prefix that precedes
the name of the bucket you have designated for log file delivery.
:type sns_topic_name: string
:param sns_topic_name: Specifies the name of the Amazon SNS topic
defined for notification of log file delivery.
:type include_global_service_events: boolean
:param include_global_service_events: Specifies whether the trail is
publishing events from global services such as IAM to the log
files.
:type trail: dict
:param trail: Represents the Trail structure that contains the
CloudTrail setting for an account.
:param trail: Support for passing a Trail object in the CreateTrail or
UpdateTrail actions will end as early as February 15, 2014. Instead
of the Trail object and its members, use the parameters listed for
these actions.
"""
params = {}
if name is not None:
params['Name'] = name
if s3_bucket_name is not None:
params['S3BucketName'] = s3_bucket_name
if s3_key_prefix is not None:
params['S3KeyPrefix'] = s3_key_prefix
if sns_topic_name is not None:
params['SnsTopicName'] = sns_topic_name
if include_global_service_events is not None:
params['IncludeGlobalServiceEvents'] = include_global_service_events
if trail is not None:
params['trail'] = trail
return self.make_request(action='UpdateTrail',
Expand Down

0 comments on commit aeafe9b

Please sign in to comment.