Metadata-Version: 1.1
Name: sgtools
Version: 0.5
Summary: Standard UNIX tools for manipulating AWS security group rules
Home-page: http://github.com/RetailMeNot/sgtools
Author: Matthew Wedgwood
Author-email: mw@rmn.com
License: MIT
Description: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
        Security Group Management Rule Management in Situ
        %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
        
        Concepts
        ********
        
        Security Groups rules in AWS have four basic components. In Situ and this
        documentation, we refer to them as follows:
        
        * A *direction*, "in" (ingress) or "out" (egress)
        * An *owner*, the group to whom the rule belongs
        * An *other*, the subject of the rule, which may be a security group or CIDR
        * A *portspec*, consisting of an IP protocol, low port, and high port
        
        Included Tools
        **************
        
        Situ includes two tools for managing security group rules: ``sgtables`` and ``sgmanager``.
        
        ``sgmanager`` is a higher-level tool used for managing more human-friendly rule
        representations. ``sgmanager`` depends on ``sgtables`` to make changes in AWS.
        
        ``stgables`` is a low-level (*raw*) rule processor. It consumes and generates
        basic rule definitions, and is capable of modifying rulesets in AWS.
        
        These tools only manage security group *rules*. They do not create or remove
        the groups themselves.
        
        Using ``sgmanager``
        *******************
        
        .. hint::
            You can type ``sgmanager --help`` for detailed help about the ``sgmanager`` CLI.
        
        There are currently three ``sgmanager`` subcommands:
        
        * *groupdefs*, a tool for extracting group definitions in the ``sgmanager``
        * format *render*, which accepts one or more configuration files and renders
          them to raw rules suitable for consumption by ``sgtables``
        * *reverse*, which can help you convert ``sgtables`` output to a set of rules
        
        When using ``sgmanager``, *vars_files* are files in the ``sgmanager``
        configuration format as outlined below. *input_files* refer to files containing
        raw rules as output by ``sgtables``.
        
        .. hint::
            ``sgmanager`` configurations can be broken into several files for
            flexibility. Consider storing accounts, CIDRs, and portspecs separately
            from group definitions and rules.
        
        ``sgmanager`` Configuration
        ---------------------------
        
        There are four entity types that can be defined in an sgmanager configuration:
        
        * Rule - represents a single IpPermission on a SecurityGroup
        * SecurityGroup - represents a single AWS SecurityGroup
        * Cidr - An IPv4 CIDR address/mask
        * Account - an AWS account
        
        
        The syntax of an sgmanager configuration is::
        
            <rule>          ::= "rule " <Direction> " " <SecurityGroup:NAME> " " ( <SecurityGroup:NAME> | <Cidr:NAME> ) " " <PortSpec:NAME>
        
            <SecurityGroup> ::= "sg " NAME " " SG_ID
        
            <Cidr>          ::= "cidr " NAME " " IPADDR "/" INT_MASK
            
            <Account>       ::= "acct " NAME " " ACCOUNT_ID
        
            <PortSpec>      ::= "proto " NAME " " <Protocol> " " <Lport> " " <Hport>
            <Protocol>      ::= ( "icmp" | "tcp" | "udp" | -1 | 0 | POSITIVE_INTEGER )
            <Lport>         ::= -1 | 0 | POSITIVE_INTEGER
            <Hport>         ::= -1 | 0 | POSITIVE_INTEGER
        
        Where:
        
        * ``SG_ID`` is an AWS security group id
        * ``IPADDR`` is an IPv4 address
        * ``INT_MASK`` is an integer between 0 and 32 (inclusive)
        * ``ACCOUNT_ID`` is an AWS numeric account ID
        
        For port numbers, ``POSITIVE_INTEGER`` can be between 1 and 65535, and -1 means *all*.
        
        
        Example
        -------
        
        Suppose you have a sgmanager configuration file named "myrules" containing the following::
        
            acct prd 11223344556677
            
            cidr prd-w1 10.208.0.0/16
            
            sg prd-w1-eop sg-12345678
            sg prd-w1-app sg-abcdef12
            
            proto ssh tcp 22 22
            
            rule in prd-w1-eop prd-w1-app ssh
            rule in prd-w1-eop prd-w1 ssh
        
        Running ``sgmanager prd myrules`` would produce the following output::
        
            in sg-12345678 sg-abcdef12 tcp 22 22
            in sg-12345678 10.208.0.0/16 tcp 22 22
        
        Using ``sgtables``
        ******************
        
        .. hint::
            See the output of ``sgtables --help`` for complete, current information
            about available options.
        
        ``sgtables`` has four functions: *list*, *add*, *remove*, and *update*
        
        ``sgtables`` always requires an AWS profile (from ~/.aws/config), a region, and
        a specific VPC to operate against (or the special name 'classic' for EC2
        Classic). ``sgtables`` only operates on one network at a time. EC2 classic is
        handled as its own network/VPC.
        
        All data-modification commands (everything except *list*) accept a ``--noop``
        argument (for no-op) that prevents any real changes from taking place. You can
        use the ``--verbose`` flag to see more detail about the operations performed by
        the command. ``--debug`` will also include low-level details.
        
        The *add* command will try to add all rules passed to it (so long as the group
        exists in the VPC). Similarly, *remove* will try to remove all rules passed to
        it. You will be warned if the given rule already exists (for *add*) or if it is
        not found (for *remove*), but this will not cause ``sgtables`` to fail.
        
        *update* behaves somewhat differently than the other two. Before making changes,
        *update* inspects the current ruleset and compares it to the input given. For
        any security group **mentioned as an owner in the rules list**, rules are added
        if needed, then rules are removed. To put it another way, *update* expects that
        the rules passed to it are the **only** rules that should be in those groups.
        
        *Mentioned*, in this context, means that any rule not listed as an owner in the
        ruleset will not be updated. ``sgtables`` can update all rules in all security
        groups in a VPC if passed the ominuously-named ``--obliterate`` flag to
        *update*. When ``--obliterate`` is specified, ``sgtables`` assumes that the
        rules given to it are the **only** rules that should exist in the VPC. If a
        group exists but no rules are defined for it, that group will have all of its
        rules removed.
        
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet
