# Permissions are justified

- **Pattern:** `ab-001340` (`extension-permissions-security.host-permissions-minimization.permission-justification`)
- **Severity:** info
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001340
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001340)

## Why it matters

Chrome Web Store review requires permission justification documentation for extensions requesting sensitive permissions — undocumented permissions are a common cause of rejection and post-publication removal. NIST SP 800-53 AC-1 (Access Control Policy) requires that access grants be documented and justified to meet baseline governance requirements. Beyond compliance, permission documentation is a user trust mechanism: a `PERMISSIONS.md` file that explains why each permission is needed gives security-conscious users and IT administrators the information they need to make informed deployment decisions, particularly for enterprise extensions.

## Severity rationale

Info because absent permission documentation is a governance and review compliance gap rather than a direct vulnerability, but it routinely causes Chrome Web Store rejections for sensitive-permission extensions.

## Remediation

Create a `PERMISSIONS.md` file at the project root documenting every permission in `manifest.json` with a one-line justification.

```markdown
<!-- PERMISSIONS.md -->
| Permission | Reason |
|-----------|--------|
| storage | Store user preferences locally |
| activeTab | Read current page content on user click |
| notifications | Alert user when monitored condition triggers |
```

Reference this file in your README and link it from your Chrome Web Store listing's privacy practices section. Chrome Web Store review teams look for this documentation when evaluating sensitive-permission extensions.

## Detection

- **ID:** `permission-justification`
- **Severity:** `info`
- **What to look for:** Enumerate all permissions in `manifest.json`. For each, search for documentation in README, PRIVACY.md, permissions.md, or inline comments explaining *why* that permission is needed. Count the ratio of documented permissions to total permissions.
- **Pass criteria:** Documentation exists explaining at least 1 permission usage justification, either in README.md, PRIVACY.md, or comments near the manifest. Report the count of documented permissions.
- **Fail criteria:** No documentation on why any permissions are needed.
- **Skip (N/A) when:** Always applicable for good hygiene.
- **Detail on fail:** `"No documentation found justifying requested permissions."`
- **Remediation:** Maintain a "Permission Justification" doc alongside your `manifest.json`. It helps during Chrome Web Store review and builds trust with users.

  ```markdown
  <!-- PERMISSIONS.md -->
  | Permission | Reason |
  |-----------|--------|
  | storage | Store user preferences |
  | activeTab | Read current page on user click |
  ```

---

## External references

- external chrome-cws-permission-justification — https://developer.chrome.com/docs/webstore/program-policies/permissions
- nist AC-1

Taxons: access-control

HTML version: https://auditbuffet.com/patterns/ab-001340