# IAM Floyd

[![Source](https://img.shields.io/github/stars/udondan/iam-floyd?logo=github&label=GitHub%20Stars)](https://github.com/udondan/iam-floyd)
[![iam-floyd](https://img.shields.io/github/v/release/udondan/iam-floyd)](https://github.com/udondan/iam-floyd)
[![libraries.io](https://img.shields.io/badge/packages-libraries.io-yellow)](https://libraries.io/search?q=iam-floyd)
[![CDKio](https://img.shields.io/badge/awscdk.io-cdk--iam--floyd-orange)](https://awscdk.io/packages/cdk-iam-floyd@0.72.0)
[![GitHub](https://img.shields.io/github/license/udondan/iam-floyd)](https://github.com/udondan/iam-floyd/blob/main/LICENSE)
[![Maintainability](https://api.codeclimate.com/v1/badges/cdb84b5646c6805b1a23/maintainability)](https://codeclimate.com/github/udondan/iam-floyd/maintainability)

<!-- put back - when we actually have tests
[![Test Coverage](https://api.codeclimate.com/v1/badges/cdb84b5646c6805b1a23/test_coverage)](https://codeclimate.com/github/udondan/iam-floyd/test_coverage)
-->

**AWS [IAM policy statement](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_statement.html) generator with fluent interface.**

<!-- stats -->

Support for:

* 239 Services<br>
* 7955 Actions<br>
* 781 Resource Types<br>
* 466 Conditions

<!-- /stats -->

![EXPERIMENTAL](https://img.shields.io/badge/stability-experimantal-orange?style=for-the-badge)**<br>This is an early version of the package. The API will change while I implement new features. Therefore make sure you use an exact version in your `package.json` before it reaches 1.0.0.**

[![Auto completion demo](https://raw.githubusercontent.com/udondan/iam-floyd/main/docs/movie-preview.png)](https://www.youtube.com/watch?v=ivG6VnbwMB0)

## <a name='Packages'></a>Packages

There are two different package variants available:

* **iam-floyd**: Can be used in AWS SDK, Boto 3 or for whatever you need an IAM policy statement for <br>[![npm](https://img.shields.io/npm/dt/iam-floyd?label=npm&color=blueviolet)](https://www.npmjs.com/package/iam-floyd)
  [![PyPI](https://img.shields.io/pypi/dm/iam-floyd?label=pypi&color=blueviolet)](https://pypi.org/project/iam-floyd/)
  [![NuGet](https://img.shields.io/nuget/dt/IAM.Floyd?label=nuget&color=blueviolet)](https://www.nuget.org/packages/IAM.Floyd/)
* **cdk-iam-floyd**: Integrates into [AWS CDK](https://aws.amazon.com/cdk/) and extends [`iam.PolicyStatement`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-iam.PolicyStatement.html)<br>[![npm](https://img.shields.io/npm/dt/cdk-iam-floyd?label=npm&color=orange)](https://www.npmjs.com/package/cdk-iam-floyd)
  [![PyPI](https://img.shields.io/pypi/dm/cdk-iam-floyd?label=pypi&color=orange)](https://pypi.org/project/cdk-iam-floyd/)
  [![NuGet](https://img.shields.io/nuget/dt/CDK.IAM.Floyd?label=nuget&color=orange)](https://www.nuget.org/packages/CDK.IAM.Floyd/)

Find them all on [libraries.io](https://libraries.io/search?q=iam-floyd).

---
<!-- vscode-markdown-toc -->

* [Packages](#Packages)
* [Usage](#Usage)
* [Examples](#Examples)
* [Methods](#Methods)

  * [allow](#allow)
  * [deny](#deny)
  * [to*, to](#toto)
  * [allActions](#allActions)
  * [allMatchingActions](#allMatchingActions)
  * [allListActions](#allListActions)
  * [allReadActions](#allReadActions)
  * [allWriteActions](#allWriteActions)
  * [allPermissionManagementActions](#allPermissionManagementActions)
  * [allTaggingActions](#allTaggingActions)
  * [if*, if](#ifif)
  * [on*, on](#onon)
  * [notActions](#notActions)
  * [notResources](#notResources)
  * [notPrincipals](#notPrincipals)
  * [for*](#for)
* [Collections](#Collections)

  * [allowEc2InstanceDeleteByOwner](#allowEc2InstanceDeleteByOwner)
* [FAQ](#FAQ)

  * [Why should I use this package instead of writing my policies by hand?](#WhyshouldIusethispackageinsteadofwritingmypoliciesbyhand)
  * [How often will there be updates to reflect IAM changes?](#HowoftenwilltherebeupdatestoreflectIAMchanges)
  * [Do you release new packages when a new CDK version is released?](#DoyoureleasenewpackageswhenanewCDKversionisreleased)
  * [Is the package following semantic versioning?](#Isthepackagefollowingsemanticversioning)
  * [I don't like method chaining!](#Idontlikemethodchaining)
* [Floyd?](#Floyd)
* [Similar projects](#Similarprojects)
* [Legal](#Legal)

<!-- vscode-markdown-toc-config
	numbering=false
	autoSave=true
	/vscode-markdown-toc-config --><!-- /vscode-markdown-toc -->

## <a name='Usage'></a>Usage

Depending on [your scenario](#Packages), you need to either import `iam-floyd` or `cdk-iam-floyd`:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
# for use without AWS CDK use the iam-floyd package
import iam_floyd as statement

# for use with CDK use the cdk-iam-floyd package
import cdk_iam_floyd as statement
```

Both packages contain a statement provider for each AWS service, e.g. `Ec2`. A statement provider is a class with methods for each and every available action, resource type and condition. Calling such method will add the action/resource/condition to the statement:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().to_start_instances()
```

Every method returns the statement provider, so you can chain method calls:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().to_start_instances().to_stop_instances()
```

The default effect of any statement is `Allow`. To add some linguistic sugar you can explicitly call the `allow()` method:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().to_start_instances().to_stop_instances()
```

And of course `deny()`:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().deny().to_start_instances().to_stop_instances()
```

If you don't want to be verbose and add every single action manually to the statement, you can work with [access levels](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_understand-policy-summary-access-level-summaries.html#access_policies_access-level). For every access level there is a distinct method available to add all related actions to the statement:

* `allListActions()`
* `allReadActions()`
* `allWriteActions()`
* `allPermissionManagementActions()`
* `allTaggingActions()`

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().deny().all_permission_management_actions()

statement.Ec2().allow().all_list_actions().all_read_actions()
```

To add actions based on regular expressions, use the method `allMatchingActions()`.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().deny().all_matching_actions("/vpn/i")
```

To add all actions (e.g. `ec2:*`), call the `allActions()` method:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().all_actions()
```

For every available condition key, there are `if*()` methods available.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().to_start_instances().if_encrypted().if_instance_type(["t3.micro", "t3.nano"]).if_associate_public_ip_address(False).if_aws_request_tag("Owner", "John")
```

If you want to add a condition not covered by the available methods, you can define just any condition yourself via `if()`:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().to_start_instances().if("aws:RequestTag/Owner", "John")
```

The default operator for conditions of type [String](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_String) is `StringLike`.

Most of the `if*()` methods allow an optional operator as last argument:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().to_start_instances().if("aws:RequestTag/Owner", "*John*", "StringEquals")
```

Statements without principals, by default, apply to all resources. To limit to specific resources, add them via `on*()`.

For every resource type an `on*()` method exists:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.S3().allow().all_actions().on_bucket("some-bucket").on_object("some-bucket", "some/path/*")
```

If instead you have an ARN ready, use the `on()` method:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.S3().allow().all_actions().on("arn:aws:s3:::some-bucket", "arn:aws:s3:::another-bucket")
```

To invert the policy you can use `notActions()` and `notResources()`:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.S3().allow().not_actions().not_resources().to_delete_bucket().on_bucket("some-bucket")
```

## <a name='Examples'></a>Examples

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
policy = {
    "Version": "2012-10-17",
    "Statement": [
        statement.Ec2().allow().to_start_instances().if_aws_request_tag("Owner", "${aws:username}"),
        statement.Ec2().allow().to_stop_instances().if_resource_tag("Owner", "${aws:username}"),
        statement.Ec2().allow().all_list_actions().all_read_actions()
    ]
}
```

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
policy = {
    "Version": "2012-10-17",
    "Statement": [
        statement.Cloudformation().allow().all_actions(),
        statement.All().allow().all_actions().if_aws_called_via("cloudformation.amazonaws.com"),
        statement.S3().allow().all_actions().on("arn:aws:s3:::cdktoolkit-stagingbucket-*"),
        statement.Account().deny().all_permission_management_actions().all_write_actions(),
        statement.Organizations().deny().all_permission_management_actions().all_write_actions()
    ]
}
```

## <a name='Methods'></a>Methods

### <a name='allow'></a>allow

Sets the `Effect` of the statement to `Allow`.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().to_stop_instances()
```

### <a name='deny'></a>deny

Sets the `Effect` of the statement to `Deny`.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().deny().to_stop_instances()
```

### <a name='toto'></a>to*, to

For every available action, there are `to*()` methods available.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().to_start_instances().to_stop_instances()
```

### <a name='allActions'></a>allActions

This method adds all actions of the related service to the statement, e.g. `ec2:*`

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().all_actions()
```

### <a name='allMatchingActions'></a>allMatchingActions

Adds all actions matching regular expressions to the statement.

The regular expressions need to be in [Perl/JavaScript literal style](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) and need to be passed as strings:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().all_matching_actions("/vpn/i")
```

### <a name='allListActions'></a>allListActions

Adds all actions with [access level](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_understand-policy-summary-access-level-summaries.html#access_policies_access-level) **list** to the statement.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().all_list_actions()
```

### <a name='allReadActions'></a>allReadActions

Adds all actions with [access level](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_understand-policy-summary-access-level-summaries.html#access_policies_access-level) **read** to the statement.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().all_read_actions()
```

### <a name='allWriteActions'></a>allWriteActions

Adds all actions with [access level](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_understand-policy-summary-access-level-summaries.html#access_policies_access-level) **write** to the statement.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().all_write_actions()
```

### <a name='allPermissionManagementActions'></a>allPermissionManagementActions

Adds all actions with [access level](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_understand-policy-summary-access-level-summaries.html#access_policies_access-level) **permission management** to the statement.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().all_permission_management_actions()
```

### <a name='allTaggingActions'></a>allTaggingActions

Adds all actions with [access level](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_understand-policy-summary-access-level-summaries.html#access_policies_access-level) **tagging** to the statement.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().all_tagging_actions()
```

### <a name='ifif'></a>if*, if

For every available condition key, there are `if*()` methods available.

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().to_start_instances().if_encrypted().if_instance_type(["t3.micro", "t3.nano"]).if_associate_public_ip_address(False).if_aws_request_tag("Owner", "John")
```

Most of them allow an optional operator as last argument:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().to_start_instances().if_instance_type("*.nano", "StringLike")
```

[Global conditions](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) are prefixed with `ifAws`, e.g. `ifAwsRequestedRegion()`

If you want to add a condition not covered by the available methods, you can define just any condition yourself via `if()`:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Ec2().allow().to_start_instances().if("aws:RequestTag/Owner", "${aws:username}", "StringEquals")
```

### <a name='onon'></a>on*, on

Limit statement to specified resources.

For every resource type an `on*()` method exists:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.S3().allow().all_actions().on_bucket("some-bucket")
```

If instead you have an ARN ready, use the `on()` method:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.S3().allow().all_actions().on("arn:aws:s3:::some-bucket")
```

If no resources are applied to the statement, it defaults to all resources (`*`). You can also be verbose and set this yourself:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.S3().allow().all_actions().on("*")
```

### <a name='notActions'></a>notActions

Switches the policy provider to use [NotAction](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notaction.html).

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.S3().allow().not_actions().to_delete_bucket().on_bucket("some-bucket")
```

### <a name='notResources'></a>notResources

Switches the policy provider to use [NotResource](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notresource.html).

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.S3().allow().not_resources().to_delete_bucket().on_bucket("some-bucket")
```

### <a name='notPrincipals'></a>notPrincipals

Switches the policy provider to use [NotPrincipal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notprincipal.html).

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Sts().deny().not_principals().to_assume_role().for_user("1234567890", "Bob")
```

### <a name='for'></a>for*

To create assume policies, use the `for*()` methods. There are methods available for any type of principal:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Sts().allow().to_assume_role().for_account("1234567890")

statement.Sts().allow().to_assume_role_with_sAML().for_service("lambda.amazonaws.com")

statement.Sts().allow().to_assume_role().for_user("1234567890", "Bob")

statement.Sts().allow().to_assume_role().for_role("1234567890", "role-name")

statement.Sts().allow().to_assume_role_with_sAML().for_federated_cognito()

statement.Sts().allow().to_assume_role_with_sAML().for_federated_amazon()

statement.Sts().allow().to_assume_role_with_sAML().for_federated_google()

statement.Sts().allow().to_assume_role_with_sAML().for_federated_facebook()

statement.Sts().allow().to_assume_role_with_sAML().for_saml("1234567890", "saml-provider")

statement.Sts().allow().to_assume_role().for_public()

statement.Sts().allow().to_assume_role().for_assumed_role_session("123456789", "role-name", "session-name")

statement.Sts().allow().to_assume_role().for_canonical_user("userID")

statement.Sts().allow().to_assume_role().for("arn:foo:bar")
```

To reverse the assume policy you can call the `notPrincipals()` method:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Sts().deny().not_principals().to_assume_role().for_user("1234567890", "Bob")
```

If you use the cdk variant of the package you should not have the need to manually create assume policies. But if you do, there is an additional method `forCdkPrincipal()` which takes any number of [`iam.IPrincipal`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-iam.IPrincipal.html) objects:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.Sts().allow().to_assume_role().for_cdk_principal(
    iam.ServicePrincipal("sns.amazonaws.com"),
    iam.ServicePrincipal("lambda.amazonaws.com"))
```

## <a name='Collections'></a>Collections

The package provides commonly used statement collections. These can be called  via `new statement.Collection().allowEc2InstanceDeleteByOwner()`. Collections return a list of statements, which then can be used in a policy like this:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
policy = {
    "Version": "2012-10-17",
    "Statement": [
        (SpreadElement ...new statement.Collection().allowEc2InstanceDeleteByOwner()
          statement.Collection().allow_ec2_instance_delete_by_owner())
    ]
}
```

In Python you would need to convert the statements to JSON first:

```python
import iam_floyd as statement

statements = statement.Collection().allow_ec2_instance_delete_by_owner()

policy = {
    'Version': '2012-10-17',
    'Statement': list(map(lambda x: x.to_json(), statements)),
}
```

Available collections are:

* **allowEc2InstanceDeleteByOwner**: Allows stopping EC2 instance only for the user who started them

### <a name='allowEc2InstanceDeleteByOwner'></a>allowEc2InstanceDeleteByOwner

Allows stopping EC2 instance only for the user who started them.

## <a name='FAQ'></a>FAQ

### <a name='WhyshouldIusethispackageinsteadofwritingmypoliciesbyhand'></a>Why should I use this package instead of writing policies by hand?

All actions, conditions and resource types of every service are explorable via code suggestion. The related documentation is available in the method description. In most cases you can avoid reading the documentation completely.

IntelliSense makes it super easy to find what you're looking for. But it also helps with discovering things you were not looking for! Users write more secure/restrictive policies because they can easily type `.if` and add conditions with a `<tab>` without looking up multiple documentation pages.

By calling methods of a class you protect yourself against typos. If your code doesn't compile/run because of a typo, you'll immediately notice. If instead you have a typo in your action list, IAM will silently accept your policy. You won't notice until you see a warning in the IAM console.

Allowing/Denying all actions based on [access level](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_understand-policy-summary-access-level-summaries.html#access_policies_access-level) is a feature AWS missed when designing IAM policies. With this package it is as easy as calling `.allWriteActions()`,  `.allReadActions()` etc.

In IAM policies you can use wildcards to add actions to the statement. Wildcards often do not have enough power to define patterns and quickly include too many actions. This package enables you to select actions with regular expressions.

Limiting actions to specific resources via ARN is cumbersome. In this package, for every resource type there is a method, which not only helps with ARN creation - it also adds context to the code which helps to understand the meaning. The classical example here is to allow all actions on an S3 bucket and its containing objects:

```json
{
  "Effect": "Allow",
  "Action": "s3:*",
  "Resource": [
    "arn:aws:s3:::example-bucket"
    "arn:aws:s3:::example-bucket/*"
  ]
}
```

The first resource element is for the bucket itself. The second element is for the contained objects.

A beginner might make the mistake to think the first entry is superfluous and remove it. This package has distinct methods to limit actions to a bucket and/or objects:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
statement.S3().allow().all_actions().on_bucket("example-bucket").on_object("example-bucket", "*")
```

And yes, it's shorter too.

### <a name='HowoftenwilltherebeupdatestoreflectIAMchanges'></a>How often will there be updates to reflect IAM changes?

Once per hour the AWS documentation is checked for updates. If anything changes, a new package will be released immediately.

### <a name='DoyoureleasenewpackageswhenanewCDKversionisreleased'></a>Do you release new packages when a new CDK version is released?

No. I believe it's a myth and a user error if packages are incompatible with new releases of the CDK. `cdk-iam-floyd` is based on cdk `^1.30.0` and so far I have not seen any issues.

### <a name='Isthepackagefollowingsemanticversioning'></a>Is the package following semantic versioning?

Mostly. For manual changes by developers this package follows [semver](https://semver.org/).

Automatic releases triggered by changes in the IAM documentation will always result in a minor update.

It has been observed that IAM actions have been [deleted](https://github.com/udondan/iam-floyd/releases/tag/v0.37.0) or [renamed](https://github.com/udondan/iam-floyd/releases/tag/v0.19.0). This case will not be reflected by a major update! If you had been using such a method your code will break. On the other hand, your code probably already is broken, since it creates a policy with invalid actions until you update to the latest release.

### <a name='Idontlikemethodchaining'></a>I don't like method chaining!

That's not a question. But yes, you can completely avoid method chaining:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
my_statement = statement.Ec2()
my_statement.allow()
my_statement.to_start_instances()
my_statement.to_stop_instances()
```

## <a name='Floyd'></a>Floyd?

George Floyd has been murdered by racist police officers on May 25, 2020.

This package is not named after him to just remind you of him and his death. I want this package to be of great help to you and I want you to use it on a daily base. Every time you use it, I want you to remember our society is ill and needs change. The riots will stop. The news will fade. The issue persists!

If this statement annoys you, this package is not for you.

## <a name='Similarprojects'></a>Similar projects

* [cdk-iam-actions](https://github.com/spacerat/cdk-iam-actions)
* [cdk-iam-generator](https://github.com/srihariph/cdk-iam-generator)
* [iam-policy-generator](https://github.com/aletheia/iam-policy-generator)
* [policyuniverse](https://github.com/Netflix-Skunkworks/policyuniverse)
* [policy_sentry](https://github.com/salesforce/policy_sentry)

## <a name='Legal'></a>Legal

The code contained in the [lib/generated](https://github.com/udondan/iam-floyd/tree/main/lib/generated) folder is generated from the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_actions-resources-contextkeys.html). The class- and function-names and their description therefore are property of AWS.

AWS and their services are trademarks, registered trademarks or trade dress of AWS in the U.S. and/or other countries.

This project is not affiliated, funded, or in any way associated with AWS.
