Merge pull request #25 from 0xdabbad00/use_custom_config_file

Use custom config file

Author: 0xdabbad00

README.md

@@ -17,13 +17,93 @@ pip install parliament
 
 # Usage
 ```
-$ parliament --string '{"Version":"2012-10-17","Statement": {"Effect": "Allow","Action":["s3:GetObject"],"Resource": ["arn:aws:s3:::bucket1"]}}'
-INVALID - No resources match for s3:GetObject which requires a resource format of arn:*:s3:::*/* for the resource object* - {'filepath': None}
+cat > test.json << EOF
+{
+    "Version": "2012-10-17",
+    "Statement": {
+        "Effect": "Allow",
+        "Action":["s3:GetObject"],
+        "Resource": ["arn:aws:s3:::bucket1"]
+    }
+}
+EOF
+
+parliament --file test.json
+```
+
+This will output:
+```
+MEDIUM - No resources match for the given action -  - [{'action': 's3:GetObject', 'required_format': 'arn:*:s3:::*/*'}] - {'actions': ['s3:GetObject'], 'filepath': 'test.json'}
+```
+
+This example is showing that the action s3:GetObject requires a resource matching an object path (ie. it must have a "/" in it).
+
+## Custom config file
+You may decide you want to change the severity of a finding, the text associated with it, or that you want to ignore certain types of findings.  To support this, you can provide an override config file.  First, create a test.json file:
+
+```
+{
+    "Version": "2012-10-17",
+    "Id": "123",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Action": "s3:abc",
+        "Resource": "*"
+      },
+      {
+        "Effect": "Allow",
+        "Action": ["s3:*", "ec2:*"],
+        "Resource": "arn:aws:s3:::test/*"
+      }
+    ]
+ }
+```
+
+This will have two findings:
+- LOW - Unknown action -  - Unknown action s3:abc
+- MEDIUM - No resources match for the given action
+
+The second finding will be very long, because every s3 and ec2 action are expanded and most are incorrect for the S3 object path resource that is provided.
+
+Now create a file `config_override.yaml` with the following contents:
+
 ```
+UNKNOWN_ACTION:
+  severity: MEDIUM
+  ignore_locations:
+    filepath:
+      - testa.json
+      - .py
 
-This example is showing that a resource specifying an S3 bucket (not an object path) was given in a policy with s3:GetObject, which requires an object path. 
+RESOURCE_MISMATCH:
+  ignore_locations:
+    actions: "s3:*"
+```
+
+Now run: `parliament --file test.json --config config_override.yaml`
+You will have only one output: `MEDIUM - Unknown action -  - Unknown action s3:abc`
+
+Notice that the severity of that finding has been changed from a `LOW` to a `MEDIUM`.  Also, note that the other finding is gone, because the previous `RESOURCE_MISMATCH` finding contained an `actions` element of `["s3:*", "ec2:*"]`.  The ignore logic looks for any of the values you provide in the element within `location`.  This means that we are doing `if "s3:*" in str(["s3:*", "ec2:*"])`
+
+Now rename `test.json` to `testa.json` and rerun the command.  You will no longer have any output, because we are filtering based on the filepath for `UNKNOWN_ACTION` and filtering for any filepaths that contain `testa.json` or `.py`.
+
+You can also check the exit status with `echo $?` and see the exit status is 0 when there are no findings.  The exit status is set to the number of findings (ex. 10 findings results in an exit status of 10).
+
+
+
+
+## Using parliament as a library
+Parliament was meant to be used a library in other projects. A basic example follows.
+
+```
+from parliament import analyze_policy_string
+
+analyzed_policy = analyze_policy_string(policy_doc)
+for f in analyzed_policy.findings:
+  print(f)
+```
 
-See `./bin/parliament.py` for further examples.
 
 # Development
 Setup a testing environment

parliament/__init__.py

@@ -1,7 +1,7 @@
 """
 This library is a linter for AWS IAM policies.
 """
-__version__ = "0.3.4"
+__version__ = "0.3.5"
 
 import os
 import json
@@ -19,13 +19,27 @@
 config = yaml.safe_load(open(config_path, "r"))
 
 
+def override_config(override_config_path):
+    if override_config_path is None:
+        return
+
+    # Load the override file
+    override_config = yaml.safe_load(open(override_config_path, "r"))
+
+    # Over-write the settings
+    for finding_type, settings in override_config.items():
+        for setting, settting_value in settings.items():
+            config[finding_type][setting] = settting_value
+
+
 def enhance_finding(finding):
     if finding.issue not in config:
         raise Exception("Uknown finding issue: {}".format(finding.issue))
     config_settings = config[finding.issue]
     finding.severity = config_settings["severity"]
     finding.title = config_settings["title"]
     finding.description = config_settings.get("description", "")
+    finding.ignore_locations =  config_settings.get("ignore_locations", None)
     return finding
 
 
@@ -44,12 +58,15 @@ def analyze_policy_string(policy_str, filepath=None):
     policy.analyze()
     return policy
 
+
 class UnknownPrefixException(Exception):
     pass
 
+
 class UnknownActionException(Exception):
     pass
 
+
 def is_arn_match(resource_type, arn_format, resource):
     """
     Match the arn_format specified in the docs, with the resource
@@ -217,7 +234,9 @@ def expand_action(action, raise_exceptions=True):
         raise UnknownPrefixException("Unknown prefix {}".format(prefix))
 
     if len(actions) == 0 and raise_exceptions:
-        raise UnknownActionException("Unknown action {}:{}".format(prefix, unexpanded_action))
+        raise UnknownActionException(
+            "Unknown action {}:{}".format(prefix, unexpanded_action)
+        )
 
     return actions
 

parliament/cli.py

@@ -6,18 +6,27 @@
 import sys
 import json
 
-from parliament import analyze_policy_string, enhance_finding
+from parliament import analyze_policy_string, enhance_finding, override_config
+from parliament.misc import make_list
 
 
 def is_finding_filtered(finding, minimum_severity="LOW"):
     # Return True if the finding should not be displayed
     minimum_severity = minimum_severity.upper()
-    finding = enhance_finding(finding)
     severity_choices = ["MUTE", "INFO", "LOW", "MEDIUM", "HIGH", "CRITICAL"]
     if severity_choices.index(finding.severity) < severity_choices.index(
         minimum_severity
     ):
         return True
+
+    if finding.ignore_locations:
+        for location_type, locations_to_ignore in finding.ignore_locations.items():
+            for location_to_ignore in make_list(locations_to_ignore):
+                if (
+                    location_to_ignore.lower()
+                    in str(finding.location.get(location_type, "")).lower()
+                ):
+                    return True
     return False
 
 
@@ -40,7 +49,11 @@ def print_finding(finding, minimal_output=False, json_output=False):
     else:
         print(
             "{} - {} - {} - {} - {}".format(
-                finding.severity, finding.title, finding.description, finding.detail, finding.location
+                finding.severity,
+                finding.title,
+                finding.description,
+                finding.detail,
+                finding.location,
             )
         )
 
@@ -74,6 +87,9 @@ def main():
         help="Minimum severity to display. Options: CRITICAL, HIGH, MEDIUM, LOW, INFO",
         default="LOW",
     )
+    parser.add_argument(
+        "--config", help="Custom config file for over-riding values", type=str
+    )
     args = parser.parse_args()
 
     if args.minimal and args.json:
@@ -149,7 +165,9 @@ def main():
         exit(-1)
 
     filtered_findings = []
+    override_config(args.config)
     for finding in findings:
+        finding = enhance_finding(finding)
         if not is_finding_filtered(finding, args.minimum_severity):
             filtered_findings.append(finding)
 
@@ -160,7 +178,7 @@ def main():
     for finding in filtered_findings:
         print_finding(finding, args.minimal, args.json)
     # There were findings, so return with a non-zero exit code
-    exit(1)
+    exit(len(filtered_findings))
 
 
 if __name__ == "__main__":

parliament/finding.py

@@ -10,6 +10,7 @@ class Finding:
     severity = ""
     title = ""
     description = ""
+    ignore_locations = {}
 
     def __init__(self, issue, detail, location):
         self.issue = issue

parliament/statement.py

@@ -710,17 +710,17 @@ def analyze_statement(self):
                 expanded_actions.extend(expand_action(action))
             except UnknownActionException as e:
                 self.add_finding(
-                    "UNKNOWN_ACTION", detail=str(e), location={"string": self.stmt}
+                    "UNKNOWN_ACTION", detail=str(e), location={"unknown_action": action, "statement": self.stmt}
                 )
                 return False
             except UnknownPrefixException as e:
                 self.add_finding(
-                    "UNKNOWN_PREFIX", detail=str(e), location={"string": self.stmt}
+                    "UNKNOWN_PREFIX", detail=str(e), location={"statement": self.stmt}
                 )
                 return False
             except Exception as e:
                 self.add_finding(
-                    "EXCEPTION", detail=str(e), location={"string": self.stmt}
+                    "EXCEPTION", detail=str(e), location={"statement": self.stmt}
                 )
                 return False
 
@@ -846,7 +846,7 @@ def analyze_statement(self):
                         )
             if actions_without_matching_resources:
                 self.add_finding(
-                    "RESOURCE_MISMATCH", detail=actions_without_matching_resources
+                    "RESOURCE_MISMATCH", detail=actions_without_matching_resources, location={"actions": actions}
                 )
 
         # If conditions exist, it will be an element, which was previously made into a list