Merge pull request #308 from kmcquade/fix/GH-292-hyperlinks-to-action-api-calls

Adds hyperlinks to AWS IAM Action metadata. Adds new query for get_api_documentation_link_for_action

Author: kmcquade

docs/contributing/testing.md

@@ -76,14 +76,14 @@ Local Unit Testing and Integration Testing:
 
 * File mapping: Unit test files map directly to the .py files in the Policy Sentry package
 * Folder mapping: Folder structure of the test files maps directly to the folder structure in the Policy Sentry package
-* GitHub issue mapping: Add unit tests that correspond directly to those GitHub issues to show that the fix work specifically for the issue raised. prefix test name with issue number. 
+* GitHub issue mapping: Add unit tests that correspond directly to those GitHub issues to show that the fix work specifically for the issue raised. prefix test name with issue number.
 For example: [test_gh_211_write_with_empty_access_level_lists](https://github.com/salesforce/policy_sentry/blob/0b3398a365f4cf0901bd779c6156207688e7858b/test/writing/test_write_policy_library_usage.py#L269) is prefixed with issue number 111.
-* Adaptable to IAM Definition changes: 
+* Adaptable to IAM Definition changes:
   * For tests that are dependent on current state of the IAM definition (aka the IAM Database, iam_definition.json), avoid doing equals comparision of the results with the expected_results.
   * Over time, as IAM definiton changes, chances are that such tests would fail.
   * Example: let's say that hypothetically the secretsmanager service had 4 actions at the "write" access level that could be restricted to the secret resource type. If I wrote the tests so that they tested the value of the generated policy, that works for the initial tests. But if AWS adds two new actions that can be restricted to that access level and resource type, then the tests would fail.
   * This only really applies for where the expected test values would be dependent on the current state of the IAM definition (aka the IAM Database, iam_definition.json) and the actions in there. So, validating the output of write-policy related commands, and query related commands.
-  * After I realized that, I started writing my tests so that the expected output that showed what actions you'd want would be in the comments instead of the expected_results, so the human knows what's going on. And then I would just check that the size of the array holding the actions is greater than or equal to the size that it is currently at. 
+  * After I realized that, I started writing my tests so that the expected output that showed what actions you'd want would be in the comments instead of the expected_results, so the human knows what's going on. And then I would just check that the size of the array holding the actions is greater than or equal to the size that it is currently at.
     So, in the secretsmanager example above, the test would probably just check that the size of the actions is greater than or equal to 4.
 
 
@@ -101,8 +101,7 @@ folder.
 ./utils/run_tests.sh
 ```
 
-It will execute all of the tests that would normally be run during the
-TravisCI build. If you want to see if it will pass TravisCI, you can
+It will execute all of the tests that would normally be run during the  build. If you want to see if it will pass GitHub actions, you can
 just run that quick command on your machine.
 
 Running the Test Suite

policy_sentry/bin/cli.py

@@ -2,7 +2,7 @@
 """
     Policy Sentry is a tool for generating least-privilege IAM Policies.
 """
-__version__ = "0.11.1"
+__version__ = "0.11.2"
 import click
 from policy_sentry import command
 

policy_sentry/querying/actions.py

@@ -79,6 +79,7 @@ def get_action_data(service, action_name):
                     "action": f"{service_prefix_data['prefix']}:{this_action_name}",
                     "description": this_action_data["description"],
                     "access_level": this_action_data["access_level"],
+                    "api_documentation_link": this_action_data.get("api_documentation_link"),
                     "resource_arn_format": resource_arn_format,
                     "condition_keys": condition_keys,
                     "dependent_actions": dependent_actions,
@@ -448,3 +449,23 @@ def get_privilege_info(service_prefix, action):
     except KeyError as k_e:
         raise Exception("Unknown action {}:{}".format(service_prefix, action)) from k_e
     return privilege_info
+
+
+def get_api_documentation_link_for_action(service_prefix, action_name):
+    """
+    Given a service, like `s3` and an action name, like `ListBucket`, return the documentation link about that specific
+    API call.
+
+    Arguments:
+        service_prefix: The service prefix, like `s3`
+        action_name: An action name, like `ListBucket`
+
+    Returns:
+        List: Link to the documentation about that API call
+    """
+    rows = get_action_data(service_prefix, action_name)
+    result = None
+    for row in rows.get(service_prefix):
+        if row.get("api_documentation_link"):
+            result = row.get("api_documentation_link")
+    return result

policy_sentry/shared/awsdocs.py

@@ -242,9 +242,13 @@ def create_database(destination_directory, access_level_overrides_file):
                     priv = ""
                     # Get the privilege
                     for link in cells[0].find_all("a"):
-                        if "href" not in link.attrs:
+                        if "href" not in link.attrs:  # pylint: disable=no-else-continue
                             # Skip the <a id='...'> tags
+                            api_documentation_link = None
                             continue
+                        else:
+                            api_documentation_link = link.attrs.get('href')
+                            print(api_documentation_link)
                         priv = chomp(link.text)
                     if priv == "":
                         priv = chomp(cells[0].text)
@@ -327,6 +331,7 @@ def create_database(destination_directory, access_level_overrides_file):
                         "description": description,
                         "access_level": access_level,
                         "resource_types": resource_types,
+                        "api_documentation_link": api_documentation_link
                     }
 
                     service_schema["privileges"][priv] = privilege_schema