DOCSEARCHbyAlgolia
Submit Docs

Policy Sentry

repository·master·Indexed 24 days ago

https://github.com/salesforce/policy_sentry

An IAM Least Privilege Policy Generator that abstracts the complexity of writing secure AWS IAM policies. It allows users to define access via resource ARNs and high-level access levels (CRUD: Read, Write, List, Tagging, or Permissions management) to generate scoped-down JSON policies. The tool includes a CLI for template creation and policy writing, a local SQLite database of AWS service information, and supporting Terraform modules such as generate-iam-policies and ps-template.

Tokens
21.9K
Snippets
57
Records
112
Agent score
79%

What's inside policy_sentry

  1. Overview of Policy Sentry

    master

    Policy Sentry is an AWS IAM Least Privilege Policy Generator, auditor, and analysis database. It uses a database compiled from official AWS IAM documentation (Actions, Resources, and Condition Keys) to automate the creation of secure, least-privilege IAM policies.

    Key capabilities include:

    • Limiting Blast Radius: Restricts access to specific resources rather than using wildcards (*), preventing widespread access in the event of a credential breach.
    • Automated Policy Creation: Scales the generation of secure policies, reducing the need for manual IAM reviews.
    • Database Querying: Allows users to query the IAM database to find appropriate actions and resources.
    • Terraform Integration: Can generate IAM policies based on Terraform output.
    • Template-based Writing: Uses YAML templates to define policy requirements, including justifications, CRUD levels, and specific Amazon Resource Names (ARNs).

  2. Use the ps-template Terraform module to generate JSON policies

    master
    The ps-template Terraform module uses Policy Sentry to generate a JSON policy file based on specified access levels and resource constraints. It allows you to define granular permissions (READ, WRITE, LIST, TAGGING, and PERMISSIONS MANAGEMENT) by providing lists of Amazon Resource Names (ARNs) and managing how resource constraints are applied to specific AWS actions.

  3. Use the wildcard-only section in Policy Sentry templates

    master

    The wildcard-only section in a Policy Sentry template is used to hold IAM actions that do not support resource constraints. While most actions (like s3:GetObject) can be restricted to specific ARNs, certain actions require wildcards in the resources block of the generated policy to function correctly.

    Use the following keys within the wildcard-only block:

    • single-actions: For standalone actions that do not support resource constraints.
    • service-read, service-write, service-list, service-tagging, service-permissions-management: For service-wide actions categorized by access level (e.g., s3 or ec2).
    mode: crud
name: myRole
# Specify resource ARNs
read:
- ''
# Actions that do not support resource constraints
wildcard-only:
  single-actions: # standalone actions
  - ''
  # Service-wide, per access level - like 's3' or 'ec2'
  service-read:
  - ''
  service-write:
  - ''
  service-list:
  - ''
  service-tagging:
  - ''
  service-permissions-management:
  - ''

  4. How Policy Sentry abstracts IAM policy complexity

    master

    Policy Sentry uses an internal database of AWS documentation (Actions, Resources, and Condition Keys) to map high-level access levels to specific IAM actions.

    Instead of manually identifying every action required for a task, you provide the Resource ARN and an Access Level (e.g., Read, Write, List, Tagging, or Permissions management). Policy Sentry then aggregates the necessary actions and generates a scoped-down policy that limits the blast radius by applying those actions only to the specified resource types.

  5. How Policy Sentry compares to Repokid

    master

    Policy Sentry and Repokid are complementary tools for IAM management:

    • Repokid: A mature tool that leverages AWS Access Advisor to strip unused privileges from existing policies. It operates at the service level (e.g., S3-wide) rather than the action level, meaning its revised policies are less granular.
    • Policy Sentry: Focuses on generating granular, least-privilege policies from the start, specifically restricting actions to defined resource ARNs.

    Recommended Workflow: Use Policy Sentry to generate secure, granular policies for new roles, and use Repokid to prune existing roles that have accumulated unused permissions over time.

  6. How policy_sentry maps Actions, Resources, and Condition Keys

    master

    policy_sentry uses a database seeded from AWS documentation to map relationships between service actions and their constraints. Understanding these three tables is key to how the tool generates policies:

    1. Action Table

    Defines what an action can do and what it requires. Key columns include:

    • Actions: The IAM action name.
    • Access Level: Classification (List, Read, Write, Permissions management, or Tagging).
    • Resource Types: Indicates if the action supports resource-level permissions (restricting by ARN). If blank, the action only supports * as a resource.
    • Condition Keys: Service-specific keys available for that action.
    • Dependent Actions: Actions that must also be granted to the principal (e.g., kms:CreateCustomKeyStore requires cloudhsm:DescribeClusters).

    2. ARN Table

    Maps Resource Types (from the Action table) to specific ARN formats and available Condition Keys.

    3. Condition Keys Table

    Provides details on available condition keys, their types (e.g., Bool, String), and descriptions.

    Note: While policy_sentry imports Condition Keys into its database, it does not currently insert them into generated policies due to complexity.

  7. How Policy Sentry generates policies using access levels

    master

    Policy Sentry uses an internal database derived from AWS documentation to map specific Actions to Access Levels and Resource Types.

    When a user requests an access level for a specific resource, Policy Sentry looks up the corresponding actions. For example:

    ActionAccess LevelResource Type
    ssm:GetParameterReadparameter
    ssm:DescribeParametersListparameter
    ssm:PutParameterWriteparameter
    secretsmanager:PutResourcePolicyPermissions managementsecret
    secretsmanager:TagResourceTaggingsecret

    Users can express their requirements in high-level terms such as:

    • "I need Read/Write/List access to arn:aws:s3:::example-org-sbx-vmimport"
    • "I need Permissions Management access to arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
    • "I need Tagging access to arn:aws:ssm:us-east-1:123456789012:parameter/test"

  8. Comparison: Policy Sentry vs. Log-based Policy Generators

    master

    Log-based tools (CloudTracker, Trailscraper) generate policies by analyzing CloudTrail logs. They differ from Policy Sentry in the following ways:

    • CloudTracker: Uses Amazon Athena to query logs. It attempts to map CloudTrail actions to IAM actions, but results can be inaccurate due to naming mismatches. Generated policies often default to Resources: "*", requiring manual restriction.
    • Trailscraper: Automates generation from CloudTrail logs but has limitations: it downloads all logs (which is slow), and like CloudTracker, it often generates policies with Resources: "*" rather than specific ARNs.
    • Policy Sentry Advantage: Unlike these tools, Policy Sentry generates policies that are restricted to specific resource ARNs by design, rather than relying on post-generation manual cleanup.

  9. Comparison: Policy Sentry vs. AWS Policy Generator (static website)

    master

    The AWS Policy Generator is a useful tool for various resource-based policies (SQS, S3, SNS, VPC), but has limitations compared to Policy Sentry:

    • ARN Accuracy: The generator uses regex for resource ARNs that may not always meet actual valid ARN requirements. Policy Sentry uses more accurate resource constraints.
    • Action Coverage: The generator relies on a policies.js file that is not as well-maintained as official AWS documentation. It may miss newer or specific actions, such as:
    a4b:describe*
appstream:get*
cloudformation:preview*
codestar:verify*
ds:check*
health:get*
health:list*
kinesisanalytics:get*
lightsail:list*
mobilehub:validate*
resource-groups:describe*

  10. How CRUD Mode works

    master
    CRUD Mode is a flagship feature that allows you to build least-privilege IAM policies by specifying access levels instead of individual actions. You define CRUD levels—read, write, list, tagging, or permissions-management—and associate them with specific Resource ARNs in a YAML file. Policy Sentry then automatically generates an IAM policy where the appropriate actions are mapped to those resources.

  11. IAM Policy elements used by policy_sentry

    master

    policy_sentry generates IAM policies using the following JSON elements:

    • Version: Always uses the most recent policy language version: 2012-10-17.
    • Statement: A single statement array containing multiple statements/SIDs.
      • SID: An optional Statement ID identifier.
      • Effect: Either Allow or explicit Deny. Note that Deny overrides Allow if there is any overlap.
      • Action: The IAM action (e.g., s3:GetObject or ec2:Describe*). Supports wildcards.
      • Resource: The Amazon Resource Name (ARN) the action applies to.

    Note: The following elements are currently NOT used by policy_sentry:

    • Condition (planned for future release)
    • Principal
    • NotPrincipal
    • NotResource

  12. Comparison: Policy Sentry vs. IaC Tools (Terraform and aws-iam-generator)

    master

    Infrastructure as Code (IaC) tools manage policy lifecycle but do not inherently solve the least-privilege problem:

    • aws-iam-generator: Allows managing policies as code using Jinja2 templates. However, it requires you to write the templates from scratch and does not automatically restrict them to specific resources.
    • Terraform: Like aws-iam-generator, Terraform is a management tool. You must still manually ensure that the policy templates you write are secure and resource-constrained.
    • Policy Sentry Advantage: While IaC tools manage the deployment of policies, Policy Sentry automates the creation of the policy content itself, ensuring that Resources are restricted to specific ARNs provided by the user (e.g., via policy_sentry --write-policy).