Metadata-Version: 1.0
Name: pysec-aws
Version: 0.2
Summary: UNKNOWN
Home-page: UNKNOWN
Author: UNKNOWN
Author-email: UNKNOWN
License: UNKNOWN
Description-Content-Type: UNKNOWN
Description: # pysec-aws
        Repository approach to security groups, create easy to modify files and use cloudformation to manage your security groups.
        
        ## Sample Text File and Syntax
        ```
        ## File:   MyInternalApi_Whitelisting_Production.txt
        ## Syntax: <ip-address>/<cidr>:<portFrom>-<portTo>^<protocol>
        52.35.22.100/32:80-443^tcp
        52.35.22.101/32:443^udp
        52.35.23.0/21:80^tcp
        ```
        
        ## Install
        
        ```bash
        pip install pysec-aws
        ```
        
        ## Usage From Code
        
        ```python
        >>> import pysec
        # Loading a single file
        >>> p = pysec.SecurityTemplate(input_file_path='/mypath/MyInternalApi_Whitelisting_Production.txt')
        [INFO] File /mypath/MyInternalApi_Whitelisting_Production.txt loaded successfully - 3 ingress rules detected
        
        # Loading a folder of files
        >>> p2 = pysec.SecurityTemplate(folder_path='/mypath')
        [INFO] File /mypath/MyInternalApi_Whitelisting_Production.txt loaded successfully - 3 ingress rules detected
        [INFO] File /mypath/SecondFile.txt loaded successfully - 3 ingress rules detected
        
        >>> p
        {'requests': [{'toPort': '443', 'ip': '52.35.22.100', 'cidr': '32', 'ipProtocol': 'tcp', 'fromPort': '80'}, {'toPort': '443', 'ip': '52.35.22.101', 'cidr': '32', 'ipProtocol': 'udp', 'fromPort': '443'}, {'toPort': '80', 'ip': '52.35.23.0', 'cidr': '21', 'ipProtocol': 'tcp', 'fromPort': '80'}]}
        
        >> p.generate_template(group_name='MySecurityGroup', vpc='vpc-82c92af3')
        [INFO] Generated Troposphere object
        
        >>> p.to_file(output_file_path='/mypath/artifact.yaml', format='yml')
        [INFO] CF Template flushed to disk: /mypath/artifact.yaml
        
        >>> p.to_file(output_file_path='/mypath/artifact.json', format='json')
        [INFO] CF Template flushed to disk: /mypath/artifact.json
        
        >>> p.to_cfdict()
        {'Outputs': {'SecurityGroupId': {'Description': 'Security Group Id', 'Value': {'Ref': 'MySecurityGroup'}}}, 'Resources': {'MySecurityGroup': {'Type': 'AWS::EC2::SecurityGroup', 'Properties': {'SecurityGroupIngress': [{'ToPort': '443', 'FromPort': '80', 'IpProtocol': 'tcp', 'CidrIp': '52.35.22.100/32'}, {'ToPort': '443', 'FromPort': '443', 'IpProtocol': 'udp', 'CidrIp': '52.35.22.101/32'}, {'ToPort': '80', 'FromPort': '80', 'IpProtocol': 'tcp', 'CidrIp': '52.35.23.0/21'}], 'VpcId': 'vpc-82c92af3', 'GroupDescription': 'Security group created by PySec-AWS - MySecurityGroup'}}}}
        
        ```
        
        ## Usage From Shell
        
        ```bash
        # Initiate a new repository of rules, folder path defaults to current directory.
        $ pysec init --folder-path /mypath
        $
        
        # Configure the new repository with required configuration items, --aws-profile-name will search for AWS credential profile
        $ pysec configure --vpc-id vpc-12345678 --group-name MySecurityGroup --aws-region us-west-2 --aws-profile-name myprofile
        $
        
        # Get repository status
        $ pysec status
        [INFO] File /Users/eibissror/pysec-test/rules2 loaded successfully - 3 ingress rules found
        [INFO] File /Users/eibissror/pysec-test/test.txt loaded successfully - 3 ingress rules found
        
        File Path                             MD5 Hash (Committed)              MD5 Hash (Current)                Diff?
        ------------------------------------  --------------------------------  --------------------------------  -------
        /Users/eibissror/pysec-test/rules2    6f44c15278efcde57558fab5632390f9  6f44c15278efcde57558fab5632390f9  True
        /Users/eibissror/pysec-test/test.txt  df30553f6c6852dea7628c73fde589b7  df30553f6c6852dea7628c73fde589b7  True
        
        
        # Stage a change
        $ pysec --use-profile stage
          #  Suggested Change                                      Security Group    Action
        ---  ----------------------------------------------------  ----------------  --------------
          1  CIDR-IP: 52.33.24.1/32 FROM: 80 TO: 80 PROTOCOL: tcp  MySecurityGroup   ++ addition ++
          2  CIDR-IP: 52.35.23.0/21 FROM: 80 TO: 80 PROTOCOL: tcp  MySecurityGroup   -- removal --
        
        
        # Commit the changes using profile
        $ pysec --use-profile --yes commit
        [INFO] Creating Stack arn:aws:cloudformation:us-west-2:123456789123:stack/PysecSecurityGroup-DH447K/0ef530a0-e74a-14e7-9c17-50d5ca789eae
        [INFO] Stack created successfully
        
        # Commit the changes using API credentials
        $ pysec --aws-access-key-id AKIAIOSFODNN7EXAMPLE --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY commit
        [INFO] Creating Stack arn:aws:cloudformation:us-west-2:123456789123:stack/PysecSecurityGroup-DH447K/0ef530a0-e74a-14e7-9c17-50d5ca789eae
        [INFO] Stack created successfully
        
        # Destroy stack and repository
        $ pysec --use-profile --yes destroy
        [INFO] Deleting Stack PysecSecurityGroup-UKUQVM
        [INFO] Stack deleted successfully
        
        ```
        
        ### Artifacts
        
        ```yaml
        Outputs:
          SecurityGroupId:
            Description: Security Group Id
            Value: !Ref 'MySecurityGroup'
        Resources:
          MySecurityGroup:
            Properties:
              GroupDescription: Security group created by automated process - MySecurityGroup
              SecurityGroupIngress:
                - CidrIp: 52.35.22.100/32
                  FromPort: '80'
                  IpProtocol: tcp
                  ToPort: '443'
                - CidrIp: 52.35.22.101/32
                  FromPort: '443'
                  IpProtocol: udp
                  ToPort: '443'
                - CidrIp: 52.35.23.0/21
                  FromPort: '80'
                  IpProtocol: tcp
                  ToPort: '80'
              VpcId: vpc-82c92af3
            Type: AWS::EC2::SecurityGroup
        ```
        
        ## Use cases
        
        If you need to manage a lot of dynamic security group that allow access between multiple AWS accounts, you can use this to keep simple ip lists in your repo per environment / branch, and build them into cloudformation templates during your CICD process, it is easier to manage then making changes directly to a template stored on git.
        Alternatively, one could automate the process of building CF templates using this tool -- pull requests can trigger build and update of existing stack (this will require contributions to this tool).
        
        Consider a github repository as a source for whitelisted IP addresses:
        
        ```bash
        Repository-Root/
        ├── Production/
        │   ├── Service-A/
        │   │   ├── .pysec       # pysec state file
        │   │   ├── .hashes      # pysec files hash table
        │   │   ├── rules.pysec  # pysec rules file
        │   ├── Service-B/
        │   │   ├── .pysec
        │   │   ├── .hashes
        │   │   ├── rules.pysec
        ├── Pre-Production/
        │   ├── .../
        ```
        
        Given changes to a rules file, after cloning this repository, pysec can update relevant stacks in relevant account,
        this allows you to delegate control to other teams over relevant security groups, while letting you be a reviewer of
        said changes.
Platform: UNKNOWN
