Merge pull request #40 from PostHog/tom/permission-set-description

Allow specifying description for permission set

Author: Piccirello

CLAUDE.md

@@ -20,3 +20,47 @@ uv run --directory src --extra dev pre-commit run --all-files
 ```bash
 cd src && uv run pytest -q
 ```
+
+## Architecture Overview
+
+Terraform module that deploys AWS Lambda functions for just-in-time AWS SSO access management via Slack. Two access models exist: **account access** (temporary permission set assignment on AWS accounts) and **group access** (temporary SSO group membership).
+
+### Terraform Layer
+
+- `vars.tf` — Module inputs. Two separate config variables: `config` (account access statements) and `group_config` (group access statements), both `type = any`.
+- `s3.tf` — Serializes both to a single S3 object as `{"statements": var.config, "group_statements": var.group_config}`.
+- `locals.tf` — Validation logic (group/attribute-sync overlap checks, extracting group names from `group_config`).
+- `slack_handler_lambda.tf` / `perm_revoker_lambda.tf` — Lambda function definitions. Both read config from the same S3 object.
+
+### Python Layer (`src/`)
+
+**Config & Models:**
+- `config.py` — Loads config from S3 (`load_approval_config_from_s3`), parses into `Statement`/`GroupStatement` via `parse_statement`/`parse_group_statement`. `Config` is a Pydantic `BaseSettings` singleton with `frozenset` fields for statements, accounts, groups, permission_sets.
+- `statement.py` — `BaseStatement` (has `permission_set`, `required_group_membership`, etc.) → `Statement` (account access). `GroupStatement` is separate (does not inherit `BaseStatement`, lacks `permission_set` and `required_group_membership`). Eligibility filtering (`get_eligible_statements_for_user`) currently only applies to `Statement`, not `GroupStatement`.
+- `events.py` — `RevokeEvent`/`GroupRevokeEvent` and their `Scheduled*` wrappers. Tagged union via `action` field literal types.
+- `entities/` — Pydantic models for AWS resources (`Account`, `PermissionSet`, `SSOGroup`) and Slack users.
+
+**Request Flow (Slack → Decision → Execution):**
+- `main.py` — Slack bolt app. Handles account access shortcuts, modal interactions, button clicks. Registers handlers via `app.shortcut()`, `app.view()`, `app.action()`. The `handle_button_click` function falls through to `group.handle_group_button_click` on parse failure.
+- `group.py` — Parallel handlers for group access shortcuts, submission, and button clicks.
+- `slack_helpers.py` — View builders (`RequestForAccessView`, `RequestForGroupAccessView`), payload parsers (`ButtonClickedPayload`, `ButtonGroupClickedPayload`), message block builders. Modal uses dynamic view updates: accounts load first, then permission sets update on account selection via `dispatch_action=True`.
+- `access_control.py` — Decision logic (`make_decision_on_access_request`, `make_decision_on_approve_request`) is already unified for both Statement and GroupStatement. Execution is split: `execute_decision` (account) vs `execute_decision_on_group_request` (group).
+
+**Revocation & Scheduling:**
+- `schedule.py` — `schedule_revoke_event`/`schedule_group_revoke_event` create EventBridge schedules that fire the revoker Lambda.
+- `revoker.py` — Handles scheduled revocations, early revocations, inconsistency checks, extend-grant button posting. Parallel functions for account and group flows.
+
+**SSO Operations:**
+- `sso.py` — AWS SSO/Identity Store API calls. Account operations (create/delete assignment) and group operations (add/remove membership) are fundamentally different APIs. User lookup (`get_user_principal_id_by_email`) is shared.
+
+**Attribute Sync (separate feature):**
+- `attribute_syncer.py`, `attribute_mapper.py`, `sync_state.py`, `sync_config.py`, `sync_notifications.py` — Automatic user-to-group sync based on Identity Store attributes. Runs on its own Lambda/schedule.
+
+### Key Design Patterns
+
+- **Config uses two separate Terraform variables** (`config` and `group_config`) that map directly to `statements` and `group_statements` in the S3 JSON. Python reads these as separate lists.
+- **Pydantic models use `frozen=True`** (`ConfigDict(frozen=True)` in `entities/model.py`). Extra fields are silently ignored (default Pydantic v2 behavior, no `extra="forbid"`).
+- **`parse_group_statement` manually extracts keys** from the raw dict (doesn't pass the whole dict to Pydantic), so extra keys like `ResourceType` in the S3 JSON are harmlessly ignored.
+- **Decision logic is unified** in `access_control.py` — same `make_decision_on_access_request` handles both `FrozenSet[Statement]` and `FrozenSet[GroupStatement]`.
+- **Execution logic is deliberately split** — account and group execution have different SSO API calls, audit fields, and scheduling.
+- **Tests use Hypothesis** (`src/tests/strategies.py`) for property-based testing of statement parsing alongside standard pytest.

README.md

@@ -189,6 +189,7 @@ output "api_endpoint_url" {
 | <a name="input_logs_retention_in_days"></a> [logs\_retention\_in\_days](#input\_logs\_retention\_in\_days) | The number of days you want to retain log events in the log group for both Lambda functions and API Gateway. | `number` | `365` | no |
 | <a name="input_max_permissions_duration_time"></a> [max\_permissions\_duration\_time](#input\_max\_permissions\_duration\_time) | Maximum duration (in hours) for permissions granted by Elevator. Max number - 48 hours.<br/>  Due to Slack's dropdown limit of 100 items, anything above 48 hours will cause issues when generating half-hour increments<br/>  and Elevator will not display more then 48 hours in the dropdown. | `number` | `24` | no |
 | <a name="input_permission_duration_list_override"></a> [permission\_duration\_list\_override](#input\_permission\_duration\_list\_override) | An explicit list of duration values to appear in the drop-down menu users use to select how long to request permissions for.<br/>  Each entry in the list should be formatted as "hh:mm", e.g. "01:30" for an hour and a half. Note that while the number of minutes<br/>  must be between 0-59, the number of hours can be any number.<br/>  If this variable is set, the max\_permission\_duration\_time is ignored. | `list(string)` | `[]` | no |
+| <a name="input_permission_set_display_names"></a> [permission\_set\_display\_names](#input\_permission\_set\_display\_names) | Optional mapping of permission set names (or ARNs) to human-friendly labels<br/>shown in the Slack dropdown. Keys are AWS SSO permission set names or ARNs<br/>(as used in config statements), values are display labels.<br/>Example: { "eks-developer" = "EKS/kubectl access", "secrets-editor" = "Manage secrets" }<br/>Permission sets without a mapping display their AWS name as-is.<br/>Note: Slack limits dropdown option text to 75 characters. | `map(string)` | `{}` | no |
 | <a name="input_posthog_api_key"></a> [posthog\_api\_key](#input\_posthog\_api\_key) | PostHog API key for analytics. Leave empty to disable analytics tracking. | `string` | `""` | no |
 | <a name="input_posthog_host"></a> [posthog\_host](#input\_posthog\_host) | PostHog host URL for analytics. | `string` | `"https://us.i.posthog.com"` | no |
 | <a name="input_request_expiration_hours"></a> [request\_expiration\_hours](#input\_request\_expiration\_hours) | After how many hours should the request expire? If set to 0, the request will never expire. | `number` | `8` | no |

s3.tf

@@ -63,8 +63,9 @@ resource "aws_s3_object" "approval_config" {
   bucket = module.config_bucket.s3_bucket_id
   key    = "config/approval-config.json"
   content = jsonencode({
-    statements       = var.config
-    group_statements = var.group_config
+    statements                   = var.config
+    group_statements             = var.group_config
+    permission_set_display_names = var.permission_set_display_names
   })
   content_type = "application/json"
 

src/config.py

@@ -145,6 +145,7 @@ class Config(BaseSettings):
     accounts: frozenset[str]
     permission_sets: frozenset[str]
     groups: frozenset[str]
+    permission_set_display_names: dict[str, str]
 
     s3_bucket_for_audit_entry_name: str
     s3_bucket_prefix_for_partitions: str
@@ -190,6 +191,7 @@ def get_accounts_and_permission_sets(cls, values: dict) -> dict:  # noqa: ANN101
             _initial_config_etag = etag
             statements_raw = config_data.get("statements")
             group_statements_raw = config_data.get("group_statements")
+            permission_set_display_names = config_data.get("permission_set_display_names", {})
         else:
             # Fallback to environment variables
             statements_raw = values.get("statements")
@@ -198,6 +200,10 @@ def get_accounts_and_permission_sets(cls, values: dict) -> dict:  # noqa: ANN101
             group_statements_raw = values.get("group_statements")
             if group_statements_raw is not None and isinstance(group_statements_raw, str):
                 group_statements_raw = json.loads(group_statements_raw)
+            permission_set_display_names_raw = values.get("permission_set_display_names")
+            if isinstance(permission_set_display_names_raw, str):
+                permission_set_display_names_raw = json.loads(permission_set_display_names_raw)
+            permission_set_display_names = permission_set_display_names_raw or {}
 
         # Parse statements
         if statements_raw is not None:
@@ -227,6 +233,7 @@ def get_accounts_and_permission_sets(cls, values: dict) -> dict:  # noqa: ANN101
             "statements": frozenset(statements),
             "group_statements": frozenset(group_statements),
             "groups": groups,
+            "permission_set_display_names": permission_set_display_names,
             "s3_bucket_prefix_for_partitions": s3_bucket_prefix_for_partitions,
         }
 

src/main.py

@@ -798,6 +798,7 @@ def handle_account_selection(ack: Ack, body: dict, client: WebClient) -> SlackRe
     updated_view = slack_helpers.RequestForAccessView.update_with_permission_sets(
         view_blocks=body["view"]["blocks"],
         permission_sets=permission_sets,
+        display_names=cfg.permission_set_display_names,
     )
     return client.views_update(view_id=view_id, view=updated_view)
 

src/slack_helpers.py

@@ -129,17 +129,39 @@ def build_select_account_input_block(cls, accounts: list[entities.aws.Account])
         )
 
     @classmethod
-    def build_select_permission_set_input_block(cls, permission_sets: list[entities.aws.PermissionSet]) -> InputBlock:
-        sorted_permission_sets = sorted(permission_sets, key=lambda permission_set: permission_set.name)
+    def _get_permission_set_display_name(
+        cls,
+        ps: entities.aws.PermissionSet,
+        display_names: dict[str, str] | None = None,
+    ) -> str:
+        if display_names is not None:
+            name = display_names.get(ps.name) or display_names.get(ps.arn) or ps.name
+        else:
+            name = ps.name
+        return name[:75]
+
+    @classmethod
+    def build_select_permission_set_input_block(
+        cls,
+        permission_sets: list[entities.aws.PermissionSet],
+        display_names: dict[str, str] | None = None,
+    ) -> InputBlock:
+        sorted_permission_sets = sorted(
+            permission_sets,
+            key=lambda ps: cls._get_permission_set_display_name(ps, display_names).lower(),
+        )
         return InputBlock(
             block_id=cls.PERMISSION_SET_BLOCK_ID,
             label=PlainTextObject(text="Permission set"),
             element=StaticSelectElement(
                 action_id=cls.PERMISSION_SET_ACTION_ID,
                 placeholder=PlainTextObject(text="Select permission set"),
                 options=[
-                    Option(text=PlainTextObject(text=permission_set.name), value=permission_set.arn)
-                    for permission_set in sorted_permission_sets
+                    Option(
+                        text=PlainTextObject(text=cls._get_permission_set_display_name(ps, display_names)),
+                        value=ps.arn,
+                    )
+                    for ps in sorted_permission_sets
                 ],
             ),
         )
@@ -171,15 +193,20 @@ def update_with_accounts(cls, accounts: list[entities.aws.Account]) -> View:
         return view
 
     @classmethod
-    def update_with_permission_sets(cls, view_blocks: list, permission_sets: list[entities.aws.PermissionSet]) -> View:
+    def update_with_permission_sets(
+        cls,
+        view_blocks: list,
+        permission_sets: list[entities.aws.PermissionSet],
+        display_names: dict[str, str] | None = None,
+    ) -> View:
         view = cls.build()
         view.submit_disabled = False  # type: ignore[attr-defined]
         # Start from the current blocks, remove placeholder
         blocks = remove_blocks(view_blocks, block_ids=[cls.PERMISSION_SET_PLACEHOLDER_BLOCK_ID, cls.PERMISSION_SET_BLOCK_ID])
         # Insert permission set dropdown after account dropdown
         blocks = insert_blocks(
             blocks=blocks,
-            blocks_to_insert=[cls.build_select_permission_set_input_block(permission_sets)],
+            blocks_to_insert=[cls.build_select_permission_set_input_block(permission_sets, display_names=display_names)],
             after_block_id=cls.ACCOUNT_BLOCK_ID,
         )
         view.blocks = blocks

src/tests/conftest.py

@@ -52,6 +52,7 @@ def pytest_sessionstart(session):  # noqa: ANN201, ARG001, ANN001
                 },
             ]
         ),
+        "permission_set_display_names": json.dumps({}),
     }
     os.environ |= mock_env
 
@@ -77,6 +78,7 @@ def mock_s3_approval_config():
                 "AllowSelfApproval": True,
             }
         ],
+        "permission_set_display_names": {},
     }