Metadata-Version: 1.1
Name: rdklib
Version: 0.3.0
Summary: Rule Development Kit Library for AWS Config
Home-page: https://github.com/awslabs/aws-config-rdklib/
Author: RDK Maintainers
Author-email: rdk-maintainers@amazon.com
License: Apache License Version 2.0
Description: RDKlib
        ======
        
        .. image:: https://github.com/awslabs/aws-config-rdklib/workflows/ci/badge.svg?branch=master
            :target: https://github.com/awslabs/aws-config-rdklib/actions?query=workflow%3Aci+branch%3Amaster
        
        
        RDKlib is a Python library to enable you to **run custom AWS Config Rules at scale**. The library can be used to:
        
        + Help you to focus only on the compliance logic, while the library does the heavy lifting
        + Ease maintenance by moving the boilerplate code as a AWS Lambda Layer
        + Ease deployment by using AWS Serverless Application Repository
        
        RDKLib works in synergy with the AWS Config Rule Development Kit (https://github.com/awslabs/aws-config-rdk).
        
        Getting Started
        ===============
        
        Install the library locally
        ---------------------------
        
        ::
        
            pip install rdklib
        
        Create a rule using the RDK 
        ---------------------------
        
        The runtime of your RDK rule have to be set to python3.9-lib in the RDK to provide you the Rule template.
        
        * For periodic trigger:
        
        ::
        
            rdk create YOUR_RULE_NAME --runtime python3.9-lib --maximum-frequency TwentyFour_Hours
        
        * For configuration change trigger (for example S3 Bucket)
        
        ::
        
            rdk create YOUR_RULE_NAME --runtime python3.9-lib --resource-types AWS::S3::Bucket
        
        ..
        
            Note: you need to install the RDK (see https://github.com/awslabs/aws-config-rdk#getting-started)
        
        Deploy your rule with RDKlib layer
        ----------------------------------
        
        RDKLib is designed to work as a AWS Lambda Layer. It allows you to use the library without needing to include it in your deployment package.
        
        1. Install RDKlib layer (with AWS CLI)
        
        ::
        
            aws serverlessrepo create-cloud-formation-change-set --application-id arn:aws:serverlessrepo:ap-southeast-1:711761543063:applications/rdklib --stack-name RDKlib-Layer
            
            # Copy/paste the full change-set ARN to customize the following command
            aws cloudformation execute-change-set --change-set-name NAME_OF_THE_CHANGE_SET
        
            aws cloudformation describe-stack-resources --stack-name serverlessrepo-RDKlib-Layer
            # Copy the ARN of the Lambda layer in the "PhysicalResourceId" key (i.e. arn:aws:lambda:YOUR_REGION:YOUR_ACCOUNT:layer:rdklib-layer:1).
        
        ..
        
            Note: You can do the same step manually going to `https://console.aws.amazon.com/lambda/home#/create/function?tab=serverlessApps <https://console.aws.amazon.com/lambda/home#/create/function?tab=serverlessApps>`_ and find "rdklib"
        
        2. Deploy the rule
        
        ::
        
            rdk deploy YOUR_RULE_NAME --rdklib-layer-arn YOUR_RDKLIB_LAYER_ARN
        
        Dev Guide
        =========
        
        *class* **ClientFactory**
        -------------------------
        
        *method* **build_client()**
          Create or reuse a boto3 client. It minimizes the number of STS calls by reusing existing client, if already available.
        
          **Request Syntax**
        
          .. code-block:: python
        
            response = client_factory.build_client(
                service='string', region='string', assume_role_mode='bool')
        
          **Parameter**
        
          + **service** *(string)* -- **[REQUIRED]**
          
            The boto3 name of the AWS service
        
          + **region** *(string)* -- **[OPTIONAL]**
        
            Default: None
            The boto3 region
        
          + **assume_role_mode** *(string)* -- **[OPTIONAL]**
        
            Default: True
            By Default, ClientFactory is using AWS Config Role, which is comming from Config Rule event. 
            1) User can disable the assume_role_mode by setting it to False or set 'AssumeRoleMode' to False in Config Rules Parameter. ClientFactory will then use the attached lambda role for the execution. 
            2) User also can specify a custom role in Config Rules Parameter with 'ExecutionRoleName' as well as 'ExecutionRoleRegion' for ClientFactory
            
        *class* **ConfigRule**
        ----------------------
        
        *method* **evaluate_parameters()**
          Used to analyze the validity of the input parameters of the Config Rule.
          
          **Parameter**
          
          + **rule_parameters** *(dict)*
        
            The input parameters of the Config Rule.
          
          **Return Syntax**
            If one of the parameters is invalid, raise an InvalidParametersError error.
          
            .. code-block:: python
            
                from rdklib import InvalidParametersError
                raise InvalidParametersError("Error message to display")
          
            If the parameters are all valid, return a dict.
          
            .. code-block:: python
            
                return valid_rule_parameters
        
        *method* **evaluate_change()**
          Used to evaluate Configuration Change triggered rule.
          
          **Parameters**
          
          + **event**
          
            Lambda event provided by Config.
          
          + **client_factory** *(ClientFactory)*
          
            *ClientFactory* object to be used in this rule.
          
          + **configuration_item** *(dict)*
          
            The full configuration Item, even if oversized.
          
          + **valid_rule_parameters** *(dict)*
          
            The output of the evaluate_parameters() method.
          
          **Return Syntax**
            Return an list of *Evaluation* object(s). 
          
            .. code-block:: python
            
                return [Evaluation()]
          
            It can be an empty list, if no evaluation.
        
        
        *method* **evaluate_periodic()**
          Used to evaluate Periodic triggered rule.
          
          **Parameters**
          
          + **event**
          
            Lambda event provided by Config.
          
          + **client_factory** *(ClientFactory)*
          
            *ClientFactory* object to be used in this rule.
          
          + **valid_rule_parameters** *(dict)*
          
            The output of the evaluate_parameters() method.
          
          **Return Syntax**
            Return an list of *Evaluation* object(s). 
          
            .. code-block:: python
            
                return [Evaluation()]
            
            It can be an empty list, if no evaluation.
        
        *class* **Evaluation**
        ----------------------
        
        Class for the *Evaluation* object.
        
        **Request Syntax**
        
        .. code-block:: python
        
            evaluation = Evaluation(
                complianceType='ComplianceType',
                resourceId='string',
                resourceType='string',
                annotation='string')
        
        **Parameter**
        
        * **complianceType** *(ComplianceType)* **[REQUIRED]**
        
          Compliance type of the evaluation.
        
        * **resourceId** *(string)*
        
          Resource id of the evaluation. It gets autopopulated for Configuration Change triggered rule.
        
        * **resourceType** *(string)*
        
          Resource type of the evaluation (as per AWS CloudFormation definition). It gets autopopulated for Configuration Change triggered rule.
        
        * **annotation** *(string)*
        
          Annotation for the evaluation. It gets shorten to 255 characters automatically.
        
        *class* **ComplianceType**
        --------------------------
        
        Class for the *ComplianceType* object.
        
        **Request Syntax**
        
        Evaluation will display as "Compliant"
        
        .. code-block:: python
        
            compliance_type = ComplianceType.COMPLIANT
        
        
        Evaluation will display as "Non Compliant"
        
        .. code-block:: python
        
            compliance_type = ComplianceType.NON_COMPLIANT
        
        Evaluation will not display:
        
        .. code-block:: python
        
            compliance_type = ComplianceType.NOT_APPLICABLE
            
        *Helper functions* **rdklibtest**
        ---------------------------------
        
        *assert_successful_evaluation(\*\*kwargs)*
          Do a comparison on the list of *Evaluation* objects returned by either *evaluate_change()* or *evaluate_periodic()*.
          
          **Request Syntax**
          
          .. code-block:: python
          
            rdklibtest.assert_successful_evaluation(self, response, resp_expected, evaluations_count=1)
          
          **Parameters**
            response (list of Evaluation Objects) **[REQUIRED]**
              the list of the response from *evaluate_change()* or *evaluate_periodic()*
            resp_expected (list of Evaluation Objects) **[REQUIRED]**
              the list of the expected response from *evaluate_change()* or *evaluate_periodic()*
            evaluations_count (int)
              The number of Evaluation Objects expected. Default is 1.
        
          **Return**
            None
        
        *create_test_configurationchange_event(\*\*kwargs)*
          Generate a dummy configuration change event that can be used as input when testing *evaluate_change()*
          
          **Request Syntax**
          
          .. code-block:: python
          
            rdklibtest.create_test_configurationchange_event(invoking_event_json, rule_parameters_json=None)
        
          Parameters
            invoking_event (dict) **[REQUIRED]**
              the invoking event json from Config
            rule_parameters_json (dict)
              the key/value pair(s) for the Rule parameters. Default to None.
          
          **Return Syntax**
        
          .. code-block:: python
          
            {
                "configRuleName":"myrule",
                "executionRoleArn":"arn:aws:iam::123456789012:role/example",
                "eventLeftScope": False,
                "invokingEvent": json.dumps(invoking_event_json),
                "accountId": "123456789012",
                "configRuleArn": "arn:aws:config:us-east-1:123456789012:config-rule/config-rule-8fngan",
                "resultToken":"token",
                "ruleParameters": json.dumps(rule_parameters_json)
            }
        
        *create_test_scheduled_event(\*\*kwargs)*
          Generate a dummy periodic event that can be used as input when testing *evaluate_periodic()*
        
          **Request Syntax**
          
          .. code-block:: python
        
            rdklibtest.create_test_scheduled_event(rule_parameters_json=None)
        
          **Parameter**
            rule_parameters_json (dict)
              the key/value pair(s) for the Rule parameters. Default to None.
        
          **Return Syntax**
        
          .. code-block:: python
          
            {
                "configRuleName":"myrule",
                "executionRoleArn":"arn:aws:iam::123456789012:role/example",
                "eventLeftScope": False,
                "invokingEvent": "{\"messageType\": \"ScheduledNotification\", \"notificationCreationTime\": \"2017-12-23T22:11:18.158Z\"}",
                "accountId": "123456789012",
                "configRuleArn": "arn:aws:config:us-east-1:123456789012:config-rule/config-rule-8fngan",
                "resultToken":"token",
                "ruleParameters": json.dumps(rule_parameters_json)
            }
        
        License
        =======
        
        This project is licensed under the Apache-2.0 License.
        
        Feedback / Questions
        ====================
        
        Feel free to email rdk-maintainers@amazon.com
        
        Contacts
        ========
        * **Ricky Chau** - *Maintainer, code, testing*
        * **Mark Beacom** - *Maintainer, code, testing*
        * **Benjamin Morris** - *Maintainer, code, testing*
        * **Julio Delgado Jr.** - *Design, testing, feedback*
         
         
        Acknowledge 
        ===========
        * **Jonathan Rault** - *Maintainer, design, code, testing, feedback*
        * **Ricky Chau** - *Maintainer, code, testing*
        * **Michael Borchert** - *Design, code, testing, feedback*
        * **Joe Lee** - *Design, feedback*
        * **Chris Gutierrez** - *Design, feedback*
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
