Metadata-Version: 2.1
Name: trailscraper
Version: 0.4.4
Summary: A command-line tool to get valuable information out of AWS CloudTrail
Home-page: http://github.com/flosell/trailscraper
Author: Florian Sellmayr
Author-email: florian.sellmayr@gmail.com
License: Apache License 2.0
Description-Content-Type: UNKNOWN
Keywords: aws cloud iam cloudtrail trailscraper
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Security
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=2.7
Requires-Dist: boto3 (>=1.4.7)
Requires-Dist: click (>=6.7)
Requires-Dist: toolz (>=0.8.2)
Requires-Dist: dateparser (==0.6.0)
Requires-Dist: pytz (>=2017.3)
Requires-Dist: python-dateutil (<2.7.0)

TrailScraper
============

|PyPi Release| |Build Status|

A command-line tool to get valuable information out of AWS CloudTrail

Installation
------------

.. code:: bash

    $ pip install trailscraper

Usage
-----

.. code:: bash

    # Download some logs (including us-east-1 for global aws services)
    $ trailscraper download --bucket some-bucket \
                            --account-id some-account-id \
                            --region some-other-region \ 
                            --region us-east-1 \
                            --from 'two days ago' \
                            --to 'now' \
    # Generate an IAM Policy  
    $ trailscraper generate-policy
    {
        "Statement": [
            {
                "Action": [
                    "ec2:DescribeInstances",
                    "ec2:DescribeSecurityGroups",
                    "ec2:DescribeSubnets",
                    "ec2:DescribeVolumes",
                    "ec2:DescribeVpcs",
                ],
                "Effect": "Allow",
                "Resource": [
                    "*"
                ]
            },
            {
                "Action": [
                    "sts:AssumeRole"
                ],
                "Effect": "Allow",
                "Resource": [
                    "arn:aws:iam::1111111111:role/someRole"
                ]
            }
        ],
        "Version": "2012-10-17"
    } 

Development
-----------

.. code:: bash

    $ ./go setup   # set up venv, dependencies and tools
    $ ./go test    # run some tests
    $ ./go check   # run some style checks
    $ ./go         # let's see what we can do here

Troubleshooting
~~~~~~~~~~~~~~~

TrailScraper is missing some events
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  Make sure you have logs for the ``us-east-1`` region. Some global AWS
   services (e.g. Route53, IAM, STS, CloudFront) use this region. For
   details, check the `CloudTrail
   Documentation <http://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-global-service-events>`__

TrailScraper generated actions that aren’t IAM actions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This is totally possible. Unfortunately, there is no good,
machine-readable documentation on how CloudTrail events map to IAM
actions so TrailScraper is using heuristics to figure out the right
actions. These heuristics likely don’t cover all special cases of the
AWS world.

This is where you come in: If you find a special case that’s not covered
by TrailScraper, please `open a new
issue <https://github.com/flosell/trailscraper/issues/new>`__ or, even
better, submit a pull request.

For more details, check out the `contribution
guide <./CONTRIBUTING.md>`__

Click thinks you are in an ASCII environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``Click will abort further execution because Python 3 was configured to use ASCII as encoding for the environment.``

Set environment variables that describe your locale, e.g. :

::

    export LC_ALL=de_DE.utf-8
    export LANG=de_DE.utf-8

or

::

    LC_ALL=C.UTF-8
    LANG=C.UTF-8

For details, see
http://click.pocoo.org/5/python3/#python-3-surrogate-handling

.. |PyPi Release| image:: https://img.shields.io/pypi/v/trailscraper.svg
   :target: https://pypi.python.org/pypi/trailscraper
.. |Build Status| image:: https://travis-ci.org/flosell/trailscraper.svg?branch=master
   :target: https://travis-ci.org/flosell/trailscraper


Changelog
=========

This changelog contains a loose collection of changes in every release
including breaking changes to the API.

The format is based on `Keep a Changelog <http://keepachangelog.com/>`__

0.4.4
-----

Fixed
~~~~~

-  Made trailscraper timezone-aware. Until now, trailscraper implicitly
   treated everything as UTC, meaning relative timestamps (e.g. ``now``,
   ``two hours ago``) didn’t work properly when filtering logfiles to
   download or records to generate from. (#39)

Added
~~~~~

-  New command ``trailscraper last-event-timestamp`` to get the last
   known event timestamp.
-  New flag ``trailscraper download --wait`` to wait until events for
   the specified timeframe are found. Useful if you are waiting for
   CloudTrail to ship logs for a recent operation.

.. section-1:

0.4.3
-----

*skipped because of release-problems*

.. section-2:

0.4.2
-----

.. fixed-1:

Fixed
~~~~~

-  Fixed various special cases in mapping CloudTrail to IAM Actions:

   -  API Gateway
   -  App Stream 2
   -  DynamoDB Streams
   -  Lex
   -  Mechanical Turk
   -  S3
   -  STS
   -  Tagging

.. section-3:

0.4.1
-----

.. fixed-2:

Fixed
~~~~~

-  Ignore record files that can’t be read (e.g. not valid GZIP) in
   Python 2.7 (was only working in Python 3.\* before)
-  Fixed permissions generated for services that include the API version
   date (e.g. Lambda, CloudFront) (#20)

.. section-4:

0.4.0
-----

.. added-1:

Added
~~~~~

-  Support for CloudTrail ``lookup_events`` API that allows users to
   generate a policy without downloading logs from an S3 bucket. Note
   that this API only returns *`“create, modify, and delete API
   calls” <https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events-supported-services.html>`__*
-  ``trailscraper download`` now supports ``--from`` and ``--to`` flags
   to specify the timeframe that should be downloaded. Accepts precise
   (e.g. “2017-10-12”) and relative (e.g. “-2days”) arguments.
-  ``trailscraper generate-policy`` now supports ``--from`` and ``--to``
   to filter events to consider for the generated policy. Accepts
   precise (e.g. “2017-10-12”) and relative (e.g. “-2days”) arguments.

-  Performance optimizations: ``generate-policy`` only reads logfiles
   for the timeframe requested

-  Added ``--version`` command line argument

Changed
~~~~~~~

-  Set more flexible dependencies

Removed
~~~~~~~

-  Removed ``--past-days`` parameter in ``trailscraper download``. Was
   replaced by ``--from`` and ``--to`` (see above)

.. fixed-3:

Fixed
~~~~~

-  Ignore record files that can’t be read (e.g. not valid GZIP)

.. section-5:

0.3.0
-----

.. added-2:

Added
~~~~~

-  Support for Python >= 2.7

.. changed-1:

Changed
~~~~~~~

-  Do not download CloudTrail Logs from S3 if they already exist in the
   target folder (#9)
-  Removed dependency on fork of the awacs-library to simplify
   installation and development

.. fixed-4:

Fixed
~~~~~

-  Bug that led to policy-statements with the same set of actions not
   being combined properly in some cases (#7)

.. section-6:

0.2.0
-----

.. added-3:

Added
~~~~~

-  Basic filtering for role-arns when generating policy (#3)

.. section-7:

0.1.0
-----

*Initial Release*

.. added-4:

Added
~~~~~

-  Basic feature to download CloudTrail Logs from S3 for certain
   accounts and timeframe
-  Basic feature to generate IAM Policies from a set of downloaded
   CloudTrail logs


