File Coverage

lib/VM/EC2/Security/Policy.pm
Criterion Covered Total %
statement 7 9 77.7
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 10 12 83.3


line stmt bran cond sub pod time code
1             package VM::EC2::Security::Policy;
2              
3             =head1 NAME
4              
5             VM::EC2::Security::Policy -- Simple IAM policy generator for EC2
6              
7             =head1 SYNOPSIS
8              
9             my $policy = VM::EC2::Security::Policy->new;
10             $policy->allow('Describe*','CreateVolume','delete_volume');
11             $policy->deny('DescribeVolumes');
12             print $policy->as_string;
13              
14             =head1 DESCRIPTION
15              
16             This is a very simple Identity and Access Management (IAM) policy
17             statement generator that works sufficiently well to create policies to
18             control access EC2 resources. It is not fully general across all AWS
19             services.
20              
21             =head1 METHODS
22              
23             This section describes the methods available to
24             VM::EC2::Security::Policy. You will create a new, empty, policy using
25             new(), grant access to EC2 actions using allow(), and deny access to
26             EC2 actions using deny(). When you are done, either call as_string(),
27             or just use the policy object in a string context, to get a
28             properly-formatted policy string.
29              
30              
31             allow() and deny() return the modified object, allowing you to chain
32             methods. For example:
33              
34             my $p = VM::EC2::Security::Policy->new
35             ->allow('Describe*')
36             ->deny('DescribeImages','DescribeInstances');
37             print $p;
38              
39             =head2 $policy = VM::EC2::Security::Policy->new()
40              
41             This class method creates a new, empty policy object. The default
42             policy object denies all access to EC2 resources.
43              
44             =head2 $policy->allow('action1','action2','action3',...)
45              
46             Grant access to the listed EC2 actions. You may specify actions using
47             Amazon's MixedCase notation (e.g. "DescribeInstances"), or using
48             VM::EC2's more Perlish underscore notation
49             (e.g. "describe_instances"). You can find the list of actions in
50             L, or in the Amazon API documentation at
51             http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/OperationList-query.html.
52              
53             The "*" wildcard allows you to indicate a series of matching
54             operations. For example, to allow all Describe operations:
55              
56             $policy->allow('Describe*')
57              
58             As described earlier, allow() returns the object, making it easy to
59             chain methods.
60              
61             =head2 $policy->deny('action1','action2','action3',...)
62              
63             Similar to allow(), but in this case denies access to certain
64             actions. Deny statements take precedence over allow statements.
65              
66             As described earlier, deny() returns the object, making it easy to
67             chain methods.
68              
69             =head2 $string = $policy->as_string
70              
71             Converts the policy into a JSON string that can be passed to
72             VM::EC2->get_federation_token(), or other AWS libraries.
73              
74             =head1 STRING OVERLOADING
75              
76             When used in a string context, this object will interpolate into the
77             policy JSON string using as_string().
78              
79             =head1 SEE ALSO
80              
81             L
82             L
83              
84             =head1 AUTHOR
85              
86             Lincoln Stein Elincoln.stein@gmail.comE.
87              
88             Copyright (c) 2011 Ontario Institute for Cancer Research
89              
90             This package and its accompanying libraries is free software; you can
91             redistribute it and/or modify it under the terms of the GPL (either
92             version 1, or at your option, any later version) or the Artistic
93             License 2.0. Refer to LICENSE for the full license text. In addition,
94             please see DISCLAIMER.txt for disclaimers of warranty.
95              
96             =cut
97              
98 1     1   2326 use strict;
  1         3  
  1         37  
99              
100 1     1   7 use JSON;
  1         2  
  1         8  
101 1     1   177 use VM::EC2;
  0            
  0            
102              
103             use Carp 'croak';
104             use overload
105             '""' => 'as_string',
106             fallback => 1;
107              
108             sub new {
109             my $class = shift;
110             return bless {
111             statements => {},
112             },ref $class || $class;
113             }
114              
115             sub allow {
116             my $self = shift;
117             my @actions = @_ ? @_ : '*';
118             return $self->_add_statement(-effect=>'allow',
119             -actions=>\@actions);
120             }
121             sub deny {
122             my $self = shift;
123             my @actions = @_ ? @_ : '*';
124             return $self->_add_statement(-effect=>'deny',
125             -actions=>\@actions);
126             }
127              
128             sub _add_statement {
129             my $self = shift;
130             my %args = @_;
131             my $effect = $args{-effect} || 'allow';
132             my $actions = $args{-action} || $args{-actions} || [];
133             $actions = [$actions] unless ref $actions && ref $actions eq 'ARRAY';
134             $effect =~ /^allow|deny$/i or croak '-effect must be "allow" or "deny"';
135             foreach (@$actions) {
136             s/^ec2://i;
137             $self->{statements}{lc $effect}{ucfirst VM::EC2->uncanonicalize($_)}++ ;
138             }
139             return $self;
140             }
141              
142             sub as_string {
143             my $self = shift;
144             my $st = $self->{statements};
145              
146             my @list;
147             foreach my $effect (sort keys %$st) {
148             push @list, {
149             Action => [map { "ec2:$_" } keys %{$st->{$effect}}],
150             Effect => "\u$effect\E",
151             Resource => '*',
152             };
153             }
154              
155             unless (@list) {
156             # No statements, so deny all;
157             local $self->{statements};
158             $self->deny('*');
159             return $self->as_string;
160             }
161              
162             return encode_json({Statement => \@list});
163             }
164              
165             1;