Getting StartedΒΆ

Attention

This is an early version of the package. The API might change when new features are implemented. Therefore make sure you use an exact version in your package.json/requirements.txt before it reaches 1.0.0.

Note

Use the online policy converter to migrate any JSON policy to Floyd code!

Depending on your scenario, you need to either install/import iam-floyd or cdk-iam-floyd:

# for use without AWS CDK use the iam-floyd package
npm install iam-floyd

# for use with CDK use the cdk-iam-floyd package
npm install cdk-iam-floyd
// for use without AWS CDK use the iam-floyd package
var statement = require('iam-floyd');

// for use with CDK use the cdk-iam-floyd package
var statement = require('cdk-iam-floyd');

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:

new statement.Ec2().toStartInstances()

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

new statement.Ec2() //
  .toStartInstances()
  .toStopInstances()

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

new statement.Ec2() //
  .allow()
  .toStartInstances()
  .toStopInstances()

Or deny():

new statement.Ec2() //
  .deny()
  .toStartInstances()
  .toStopInstances()

You can work with access levels. For every access level there are distinct methods available to add all related actions to the statement:

  • allListActions()

  • allReadActions()

  • allWriteActions()

  • allPermissionManagementActions()

  • allTaggingActions()

const s1 = new statement.Ec2() //
  .deny()
  .allPermissionManagementActions();

const s2 = new statement.Ec2() //
  .allow()
  .allListActions()
  .allReadActions();

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

Important

No matter in which language you use the package, the regular expressions need to be in Perl/JavaScript literal style and need to be passed as strings!

new statement.Ec2() //
  .deny()
  .allMatchingActions('/vpn/i')

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

new statement.Ec2() //
  .allow()
  .allActions()

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

new statement.Ec2()
  .allow()
  .toStartInstances()
  .ifEncrypted()
  .ifInstanceType(['t3.micro', 't3.nano'])
  .ifAssociatePublicIpAddress(false)
  .ifAwsRequestTag('Owner', 'John')

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

new statement.Ec2()
  .allow()
  .toStartInstances()
  .if('ec2:missingCondition', 'some-value')

The default operator for conditions of type String is StringLike.

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

new statement.Ec2()
  .allow()
  .toStartInstances()
  .ifAwsRequestTag('TagWithSpecialChars', '*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:

new statement.S3()
  .allow()
  .allActions()
  .onBucket('example-bucket')
  .onObject('example-bucket', 'some/path/*')

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

new statement.S3() //
  .allow()
  .allActions()
  .on(
    'arn:aws:s3:::example-bucket', //
    'arn:aws:s3:::another-bucket'
  )

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

new statement.S3()
  .allow()
  .notActions()
  .toDeleteBucket()
  .onBucket('example-bucket')
new statement.S3()
  .allow()
  .notResources()
  .toDeleteBucket()
  .onBucket('example-bucket')
new statement.S3()
  .allow()
  .allActions()
  .notPrincipals()
  .forUser('1234567890', 'Bob')
  .onObject('example-bucket', '*')