diff --git a/.claude/commands/standardize-sections.md b/.claude/commands/standardize-sections.md new file mode 100644 index 00000000..a6a54c74 --- /dev/null +++ b/.claude/commands/standardize-sections.md @@ -0,0 +1,36 @@ +--- +description: Analyze and standardize section titles across documentation pages +--- + +You are analyzing documentation to identify inconsistent section titles and propose standardization. + +## Process + +1. **Scan the specified documentation directory** for common section patterns +2. **Identify variants** of similar sections: + - "Common Tasks" vs "Common Use Cases" vs "Use Cases" vs "Using X" + - "Getting Started" vs "Quick Start" vs "Starting Out" + - "Configuration" vs "Setup" vs "Setting Up" +3. **Count occurrences** of each variant +4. **Propose a standard** based on: + - Most common usage + - Clarity and scannability + - Consistency with existing conventions +5. **Present findings** with: + - Current state (all variants found) + - Recommended standard + - Files that need updating + - Example transformations + +## Output Format + +Provide a structured report: +- Section name variants found +- Frequency of each variant +- Recommended standard title +- List of files needing updates +- Risk assessment (breaking changes, link updates needed, etc.) + +## Example Usage + +When user runs `/standardize-sections docs/prevention`, analyze all prevention docs for section title inconsistencies and propose standardization. diff --git a/.claude/skills/batch-edit.md b/.claude/skills/batch-edit.md new file mode 100644 index 00000000..95640657 --- /dev/null +++ b/.claude/skills/batch-edit.md @@ -0,0 +1,49 @@ +# Batch Edit Helper + +When you need to make the same type of change across multiple files, this skill helps plan and execute the changes systematically. + +## When to Use + +- Terminology changes across multiple files +- Section title standardization +- Link updates after restructuring +- Formatting consistency improvements + +## Process + +1. **Planning Phase** + - Use Grep to find all instances + - Categorize instances (preserve vs replace) + - Identify edge cases + - Create todo list with one item per file + +2. **Execution Phase** + - Read each file before editing + - Make replacements systematically + - Update todo list after each file + - Track progress visibly + +3. **Verification Phase** + - Use git diff to review changes + - Check for unintended replacements + - Verify links still work + - Commit with detailed message + +## Best Practices + +- Always use Grep first to understand scope +- Read files before editing (required by Edit tool) +- Make one logical change per commit +- Use todo list to track progress across files +- Group related changes together +- Provide detailed commit messages explaining rationale + +## Example + +User: "Replace all instances of 'foo' with 'bar' in the docs" + +1. Grep for 'foo' to see all uses +2. Categorize: generic foo (replace) vs FooClass (preserve) vs foo() (evaluate) +3. Create todo list with each file +4. Execute replacements file by file +5. Commit with explanation of what was changed and why diff --git a/.claude/skills/check-terminology.md b/.claude/skills/check-terminology.md new file mode 100644 index 00000000..6a7da4cb --- /dev/null +++ b/.claude/skills/check-terminology.md @@ -0,0 +1,34 @@ +# Documentation Terminology Consistency Checker + +When invoked, analyze documentation for terminology conflicts where the same word is used with different meanings in different contexts. + +## Process + +1. Identify domain-specific terms that may conflict with product-specific features +2. Search for all uses of potentially ambiguous terms +3. Categorize uses into: + - Product-specific technical terms (should be preserved) + - Generic uses (candidates for replacement) + - Contextual uses (need case-by-case evaluation) +4. Propose alternative terminology with pros/cons +5. Present findings in a structured format with: + - Current usage patterns + - Potential confusion points + - Recommended alternatives + - Implementation strategy (hybrid, wholesale replacement, etc.) + +## Example Scenarios + +- "Policy" used for both Guardrails Policies and generic security policies +- "Resource" used for both Guardrails Resources and cloud resources +- "Control" used for both Guardrails Controls and generic security controls +- "Rule" used for both specific enforcement rules and generic guidelines + +## Output Format + +Provide a structured analysis with: +- Term being analyzed +- Distinct contexts where it appears +- Frequency in each context +- Recommended approach (preserve, replace, hybrid) +- Specific replacement suggestions with rationale diff --git a/.claude/skills/comprehensive-doc-review.md b/.claude/skills/comprehensive-doc-review.md new file mode 100644 index 00000000..0b49f8c3 --- /dev/null +++ b/.claude/skills/comprehensive-doc-review.md @@ -0,0 +1,298 @@ +# Comprehensive Documentation Review Skill + +Performs a thorough, multi-phase review of documentation sections including spelling, grammar, images, links, structure, and content quality. + +## When to Use This Skill + +Use this skill when the user requests: +- "comprehensive review" of documentation +- "thorough review" or "complete audit" +- Checking for spelling, grammar, broken links, missing images +- Verifying documentation consistency and quality +- Multi-phase review with interactive approval + +## Review Phases + +### Phase 1: Structural Inventory +**Goal**: Understand what exists and identify missing/unused resources + +Tasks: +1. List all markdown files in the target section +2. List all image files (png, jpg, gif, jpeg) +3. Identify any orphaned pages (not in sidebar) +4. Identify any unused images (not referenced in any markdown) +5. Check for duplicate/redundant pages + +**Outputs**: +- File inventory report +- Orphaned resources list +- Recommendations for cleanup + +### Phase 2: Content Validation +**Goal**: Verify all references are valid and resources exist + +Tasks: +1. Check that all image references point to existing files +2. Extract and validate all internal links +3. Check for broken fragments (#anchors) +4. Verify external links (if applicable) +5. Test sample links on localhost:3000/guardrails/docs + +**Outputs**: +- Broken references report +- Link validation results +- Suggested fixes + +### Phase 3: Spelling & Grammar +**Goal**: Identify typos, grammatical errors, and awkward phrasing + +Tasks: +1. Review each file for spelling errors +2. Check for common grammar mistakes +3. Identify inconsistent terminology +4. Flag awkward or unclear sentences +5. Check for proper capitalization of product names + +**Outputs**: +- Spelling/grammar issues by file +- Terminology inconsistencies +- Writing quality recommendations + +### Phase 4: Structure & Formatting +**Goal**: Ensure docs follow style guidelines + +Tasks: +1. Verify frontmatter presence and format +2. Check h1 matches title/sidebar_label +3. Verify no "## Overview" headers +4. Check heading hierarchy (no skipped levels) +5. Verify image syntax (markdown vs HTML) +6. Check link format (absolute paths, no .md extensions) +7. Verify code blocks have language tags + +**Outputs**: +- Style violations by file and line +- Formatting fixes needed +- Compliance score per file + +### Phase 5: Content Quality +**Goal**: Assess comprehensiveness, clarity, and usefulness + +Tasks: +1. Check parent pages are overviews with links +2. Check detail pages have comprehensive content +3. Verify "Common Use Cases" sections exist and follow format +4. Check for "Next Steps" sections with working links +5. Assess tone (conversational vs robotic) +6. Verify practical examples are present +7. Check for duplicate content between parent/child pages + +**Outputs**: +- Content quality assessment per file +- Missing sections report +- Improvement recommendations + +### Phase 6: Prevention-Specific Checks +**Goal**: Ensure prevention docs follow domain-specific guidelines + +Tasks: +1. Verify terminology (prevention vs control usage) +2. Check that security concepts are explained, not just UI +3. Verify common workflows are addressed +4. Check for concrete examples (EBS encryption, S3, etc.) +5. Verify emphasis on prevention-first approach +6. Check no exhaustive UI field listings + +**Outputs**: +- Prevention-specific compliance report +- Terminology corrections needed +- Content depth assessment + +## Interactive Review Process + +For each phase: +1. **Present findings** to user with: + - Summary of issues found + - Severity levels (critical, important, minor) + - Suggested fixes with examples + +2. **Get user approval** for: + - Which issues to fix automatically + - Which to skip or handle manually + - Whether to proceed to next phase + +3. **Apply fixes** based on approval: + - Make changes one file at a time + - Show what was changed + - Allow user to review before committing + +## Severity Levels + +**Critical (must fix)**: +- Broken image paths +- Broken internal links +- Missing frontmatter +- Wrong folder structure +- Missing required sections + +**Important (should fix)**: +- Spelling errors +- Grammar mistakes +- Inconsistent terminology +- Wrong link format (relative paths, .md extensions) +- HTML image tags without reason +- Missing alt text +- "## Overview" headers + +**Minor (nice to fix)**: +- Could improve alt text descriptions +- Writing could be more conversational +- Missing some examples +- Inconsistent capitalization +- Repeated links in same section + +## Browser Testing for Links + +When validating links against localhost:3000: +1. Use mcp__chrome-devtools tools to open pages +2. Navigate to http://localhost:3000/guardrails/docs/[path] +3. Check that page loads without 404 +4. Verify images render correctly +5. Test navigation links work + +## Report Format + +For each phase, provide a structured report: + +```markdown +# Phase [N]: [Phase Name] + +## Summary +- Files reviewed: [count] +- Issues found: [count by severity] +- Time to fix: [estimate] + +## Critical Issues +[List with file:line references and fixes] + +## Important Issues +[List with file:line references and fixes] + +## Minor Issues +[List with file:line references and fixes] + +## Recommendations +[Improvement suggestions] + +## Proposed Actions +1. [Action with estimated impact] +2. [Action with estimated impact] + +Would you like me to proceed with these fixes? +``` + +## Usage Example + +``` +User: Perform comprehensive review of prevention docs +Claude: I'll perform a comprehensive 6-phase review of the prevention documentation. Let me start with Phase 1: Structural Inventory. + +[Proceeds through each phase systematically, presenting findings and getting approval before fixes] +``` + +## Tools Required + +- **Read**: Read markdown files +- **Glob**: Find files by pattern +- **Grep**: Search for patterns in files +- **Bash**: Run commands to count, list, check files +- **Edit**: Fix issues in files +- **mcp__chrome-devtools**: Test links in browser + +## Key Checks Per Phase + +### Phase 1 Checks +```bash +# List all markdown files +find docs/prevention -name "*.md" + +# List all images +find docs/prevention -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" \) + +# Check for unused images (not referenced in any .md file) +# For each image, grep all markdown files for that image name +``` + +### Phase 2 Checks +```bash +# Extract image references from markdown +grep -h "!\[.*\](" docs/prevention/**/*.md +grep -h ' The Preventions page shows all the security controls actively protecting your cloud environment. Think of this as your inventory of preventive measuresevery Service Control Policy, Azure Policy, account setting, and other control that's stopping risky configurations before they can cause problems. +> +> Each card represents a prevention that's actually implemented in your environment. For example, you might see "Block Public ACLs on AWS S3 Buckets" or "Require encryption for Azure Storage accounts." These aren't just recommendations or desired statesthese are active controls that Guardrails has discovered in your cloud accounts. + +**Why this works:** +- Conversational tone +- Explains what it is (inventory) AND why it matters (stops risky configs) +- Concrete examples +- Clarifies it's discovered controls, not just recommendations +- Sets up the mental model for understanding the page diff --git a/.claude/skills/docs/context/style.md b/.claude/skills/docs/context/style.md new file mode 100644 index 00000000..3cad6a7a --- /dev/null +++ b/.claude/skills/docs/context/style.md @@ -0,0 +1,295 @@ +# Documentation Style Guide for LLMs + +This guide provides rules for writing and editing Turbot Guardrails documentation. + +## Core Principles + +1. **Voice**: Write in second person (you). Use collaborative third person plural only in tutorials (Let's get started). +2. **Format**: Stay in markdown. Avoid HTML unless necessary. +3. **Approach**: Use example-driven guides with progressive disclosure—start simple, then add complexity. + +## Critical Rules + +### Images + +**MUST follow these rules exactly:** + +1. **Use markdown syntax**: `![alt text](./image.png)` NOT `` + - Exception: Use `` ONLY when you must specify image size for modals/dialogs + - Full-screen images: Use markdown, no size specification + +2. **File location**: Store screenshots in the same directory as the markdown file that uses them + - DO NOT store in `/images/` directory (that's for shared icons only) + - Use relative paths: `![description](./my-image.png)` + +3. **Screenshot requirements**: + - Format: PNG only + - Size: 1280px width × 640px height (adjust height if needed to show content) + - Mode: Light mode only + - Border: No border for full-page, show border for modals + - Content: Show active pane only, not browser chrome + +4. **Taking screenshots with Chrome DevTools MCP**: + + **CRITICAL: You must resize the browser viewport BEFORE taking screenshots** + + a. **Resize the viewport to 1280px × 640px**: + - Use `mcp__chrome-devtools__resize_page` tool with `width: 1280` and `height: 640` + - This sets the viewport (content area) dimensions, NOT the browser window + - The viewport size is what matters for consistent screenshot dimensions + + b. **Adjust height if needed for content**: + - If content requires more vertical space, increase height: `height: 800`, `height: 1000`, etc. + - ALWAYS keep width at 1280px - never vary the width + - Taller screenshots are acceptable when necessary to show important content that won't fit in 640px + + c. **Take the screenshot**: + - Use `mcp__chrome-devtools__take_screenshot` with appropriate parameters + - For full-page screenshots: Use `fullPage: false` (captures current viewport) + - For specific elements: Use `uid` parameter to capture just that element + - Save to the same directory as the markdown file using `filePath` parameter + - Use kebab-case filenames: `prevention-dashboard-overview.png` + + d. **Screenshot scope**: + - Full-page screenshots: Include entire viewport width (1280px) + - Modal/dialog screenshots: Can use `uid` to capture just the modal element + - Always capture meaningful content, avoid empty states when possible + + **Example workflow**: + ``` + 1. Navigate to page: mcp__chrome-devtools__navigate_page + 2. Resize viewport: mcp__chrome-devtools__resize_page (width: 1280, height: 640) + 3. Take screenshot: mcp__chrome-devtools__take_screenshot (filePath: ./docs/prevention/dashboard/overview.png) + ``` + +### File Naming + +**All files and directories**: Use kebab-case with dashes (`-`), never underscores (`_`) +- URLs use dashes for SEO +- Apply to markdown files, directories, and images consistently + +### Folder Structure for Documentation Pages + +**CRITICAL: Each sub-page must have its own folder with its own images** + +1. **Structure requirement**: + - Each documentation page should be in its own folder as `index.md` + - Store all images for that page in the same folder + - Use relative paths `./image.png` to reference images + +2. **Correct structure example**: + ``` + docs/prevention/dashboard/ + index.md (main dashboard page) + dashboard-overview.png (image for main page) + explore/ + index.md (explore tab page) + explore-view.png (image for explore page) + reports/ + index.md (reports tab page) + reports-view.png (image for reports page) + ``` + +3. **Incorrect structure** (DO NOT DO THIS): + ``` + docs/prevention/objectives/ + index.md + benchmarks.md ❌ Should be benchmarks/index.md + objectives.md ❌ Should be objectives/index.md + benchmark-detail.png ❌ Should be in benchmark-detail/ folder + ``` + +4. **Mirror the UI structure**: + - One folder per sidebar item + - Sub-folders for each tab within a section + - Detail pages get their own folders too + +5. **When creating new documentation**: + - Always create a folder for the page: `mkdir -p docs/section/page` + - Create `index.md` inside that folder + - Take screenshots and save them in the same folder + - Reference images with `./image-name.png` + +### Document Structure + +**Every page requires:** + +```yaml +--- +title: Page Title +sidebar_label: Page Title +--- + +# Page Title +``` + +- h1 (`#`) must match `title` and `sidebar_label` exactly +- Overview paragraph(s) immediately after h1—no `## Overview` header +- Subsequent headers start at h2 (`##`) +- All headers use Title Case + +### Headers and Hierarchy + +- One h1 per page (matches frontmatter title) +- Subheaders start at h2 +- Use Title Case for all headers +- Keep section titles ≤5 words + +### Links + +**MUST follow these rules exactly:** + +1. **Use absolute paths starting with `/guardrails`**: All internal documentation links must use absolute paths + - Correct: `[Explore](/guardrails/docs/prevention/dashboard/explore)` + - Incorrect: `[Explore](./explore)` or `[Explore](explore.md)` + +2. **Omit file extensions**: Never include `.md` in links + - Correct: `[Preventions](/guardrails/docs/prevention/preventions)` + - Incorrect: `[Preventions](/guardrails/docs/prevention/preventions.md)` + +3. **Omit `index.md` for directory default pages**: When linking to a directory's index page, use the directory path only + - Correct: `[Dashboard](/guardrails/docs/prevention/dashboard)` + - Incorrect: `[Dashboard](/guardrails/docs/prevention/dashboard/index)` + - Incorrect: `[Dashboard](/guardrails/docs/prevention/dashboard/index.md)` + +4. **Link specific pages with full path**: For non-index pages, include the full filename (without extension) + - Correct: `[Explore](/guardrails/docs/prevention/dashboard/explore)` + - Correct: `[Prevention Detail](/guardrails/docs/prevention/preventions/detail)` + +5. **Frequency**: Hyperlink to relevant docs on first mention in a section only + - Do NOT repeat the same link in the same section (makes text unreadable) + +**Examples from the codebase:** +```markdown +- Use the [Explore](/guardrails/docs/prevention/dashboard/explore) tab to customize groupings +- Review [Reports](/guardrails/docs/prevention/dashboard/reports) for specialized views +- Click into any [prevention detail page](/guardrails/docs/prevention/preventions/detail) to see configuration +- Review [Objectives](/guardrails/docs/prevention/objectives) to understand which objectives +- Use [Recommendations](/guardrails/docs/prevention/recommendations) to prioritize new prevention +- Try the [Simulator](/guardrails/docs/prevention/simulator) to test Service Control Policies +``` + +### Code and UI Elements + +**In guides and instructions:** + +- **Bold** for UI elements: Select **Launch Product** button +- `Backticks` for: + - Text values: Enter `my-volume` in the **Name** field + - Code elements, CLI commands, flags: use `--var` flag + - Constants: `CREATE_COMPLETE`, `CREATE_FAILED` +- Code blocks (triple backticks) for command examples + - Always specify language: ```bash, ```json, ```hcl, ```sql + - Use standard indenting (2 spaces for tabs, align HCL after `=`) + +### Lists and Tables + +**Bullets:** +- End with period (`.`) if items are sentences or fragments +- No period if list contains simple items/keywords + +**Tables:** +- Use markdown tables when possible +- HTML `` only when markdown formatting is insufficient +- Follow bullet punctuation rules in table cells + +### Blockquotes + +Use GitHub extended blockquote types: + +- `> [!NOTE]` - Highlight important information +- `> [!TIP]` - Offer helpful advice or best practices +- `> [!IMPORTANT]` - Critical information users must not overlook +- `> [!WARNING]` - Urgent issues that may cause problems +- `> [!CAUTION]` - Potential risks or negative outcomes + +## Guide-Specific Rules + +For procedural Guardrails guides: + +### Structure + +1. Overview (no header) + - What you'll do + - What this is + - Why it matters (1-2 sentences) +2. Prerequisites (bulleted list with links) +3. Step sections (h2 headers) +4. Next Steps +5. Troubleshooting (table format) + +### Step Sections + +**Format**: `## Step {number}: {Verb} {Object}` + +Examples: +- `## Step 1: Access AWS Console` +- `## Step 2: Navigate to Products` +- `## Step 3: Find Version` + +**Requirements:** +- Include `## Step N: Monitor {Operation}` step showing how to track progress +- Final step must be `## Step N: Review` with checklist to verify success +- Use `select` for on-screen actions, `choose` for lists/dropdowns +- Link terms to glossary on first use (except in overview bullets) + +### Troubleshooting Section + +Use table format: + +| Issue | Description | Guide | +|-------|-------------|-------| +| Permission Issues | Description of the issue | [Link to guide](url) | +| Further Assistance | Contact support | [Open Support Ticket](url) | + +## Quick Reference + +### DO: +- Use markdown image syntax with relative paths for images +- Use absolute paths starting with `/guardrails` for documentation links +- Store screenshots with markdown files +- Use kebab-case for all filenames +- Bold UI elements, backtick code/values +- Use second person (you) +- Link terms once per section +- Omit `.md` extensions and `index.md` from links + +### DON'T: +- Use `` tags unless size specification required +- Use relative paths like `./page` or `../folder/page` for documentation links +- Include `.md` file extensions in links +- Store screenshots in `/images/` (that's for shared icons) +- Use underscores in filenames +- Repeat links in same section +- Use h1 for anything except page title +- Include `## Overview` header + +## Common Mistakes to Avoid + +1. **Image paths**: Writing `/images/docs/...` instead of `./image.png` +2. **Image tags**: Using `` when markdown `![]()` works +3. **File location**: Putting screenshots in `/images/` instead of with markdown +4. **Link paths**: Using relative paths `./page` or `../folder/page` instead of absolute `/guardrails/docs/...` +5. **Link extensions**: Including `.md` or `index.md` in links +6. **Links**: Repeating the same link multiple times in a section +7. **Headers**: Using `## Overview` instead of starting content immediately after h1 +8. **Naming**: Using underscores (`_`) instead of dashes (`-`) + +## Validation Checklist + +Before completing documentation work: + +- [ ] All images use markdown syntax `![alt](./file.png)` unless size needed +- [ ] All images stored in same directory as markdown file +- [ ] Browser viewport resized to 1280×640 (or 1280×[taller]) BEFORE taking screenshots +- [ ] All screenshots are 1280px wide (height can vary if needed) +- [ ] All documentation links use absolute paths starting with `/guardrails` +- [ ] No `.md` extensions or `index.md` in links +- [ ] All filenames use kebab-case with dashes +- [ ] Frontmatter includes matching `title` and `sidebar_label` +- [ ] Single h1 that matches frontmatter exactly +- [ ] No `## Overview` header (content starts after h1) +- [ ] UI elements are **bolded**, code/values have `backticks` +- [ ] Links appear once per section maximum +- [ ] Code blocks specify language +- [ ] Screenshots are PNG format, light mode diff --git a/.claude/skills/docs/skill.md b/.claude/skills/docs/skill.md new file mode 100644 index 00000000..c227b2a4 --- /dev/null +++ b/.claude/skills/docs/skill.md @@ -0,0 +1,97 @@ +# Documentation Skill + +You are an expert at writing and maintaining documentation for Turbot Guardrails. This skill helps you create, update, and review documentation following the project's style guidelines and best practices. + +## Context Files + +Before performing any documentation task, familiarize yourself with these guides: + +- **[Style Guide](context/style.md)** - Complete formatting, structure, and style rules +- **[Prevention Guide](context/prevention.md)** - Prevention-specific concepts and guidance + +## When This Skill Applies + +This skill activates when the user is: +- Writing or editing markdown documentation files +- Adding or updating screenshots +- Fixing formatting or link issues +- Reviewing documentation for compliance +- Asking about documentation standards or structure +- Working on files in the `docs/` directory + +## Routing Logic + +Based on the user's intent, route to the appropriate workflow: + +### Creating New Documentation +**Trigger words:** "write", "create", "add new page", "document" +→ Use `workflows/new-page.md` + +### Adding Screenshots +**Trigger words:** "screenshot", "add image", "take a picture", "capture" +→ Use `workflows/add-screenshots.md` + +### Fixing Links +**Trigger words:** "fix links", "update links", "broken links", "link format" +→ Use `workflows/fix-links.md` + +### Reviewing Documentation +**Trigger words:** "review", "check", "validate", "audit", "compliance check" +→ Use `workflows/review.md` + +### General Questions +If the user asks about style, structure, or best practices, answer directly using the context files. + +## Core Principles + +When working on documentation: + +1. **Conversational Tone**: Write naturally, explain WHY things matter, not just WHAT they are +2. **Image Management**: + - Store in same directory as markdown + - Use markdown syntax `![alt](./image.png)` + - Must resize browser to 1280px width before taking screenshots +3. **Link Format**: + - Absolute paths starting with `/guardrails` + - Omit `.md` extensions and `index.md` +4. **Structure**: + - Each page in its own folder as `index.md` + - All images for that page in the same folder +5. **Headers**: + - One h1 matching frontmatter title + - No `## Overview` header + - Start content immediately after h1 + +## Working with Prevention Documentation + +When documenting the Prevention section: +- Focus on explaining security concepts, not just UI elements +- Address common use cases (finding gaps, prioritizing work, testing controls) +- Explain the relationship between Objectives, Preventions, Layers, and Categories +- Use real examples (EBS encryption, S3 public access, etc.) +- Emphasize prevention-first security (stop issues before they reach production) + +## Quick Reference + +**DO:** +- Write conversationally with purpose and context +- Explain capabilities and why they matter +- Include practical scenarios and use cases +- Use markdown image syntax and relative paths +- Use absolute link paths with `/guardrails` prefix + +**DON'T:** +- Create exhaustive "Page Layout" bullet lists +- Just describe UI without explaining value +- Repeat the same link multiple times in a section +- Use HTML `` tags (except when size specification needed) +- Use relative link paths or include `.md` extensions + +## Example Invocations + +- "Write a new page documenting the prevention dashboard" +- "Add screenshots to the simulator documentation" +- "Fix all the links in the prevention section" +- "Review the objectives documentation for style compliance" +- "How should I format images in the docs?" +- "What's the correct link format for cross-references?" diff --git a/.claude/skills/docs/workflows/add-screenshots.md b/.claude/skills/docs/workflows/add-screenshots.md new file mode 100644 index 00000000..a96c5f69 --- /dev/null +++ b/.claude/skills/docs/workflows/add-screenshots.md @@ -0,0 +1,202 @@ +# Add Screenshots Workflow + +You are adding or updating screenshots for Turbot Guardrails documentation. + +## Reference Context + +Review `../context/style.md` for screenshot requirements and Chrome DevTools MCP usage. + +## Critical Requirements + +**MUST follow these rules:** + +1. **Resize viewport FIRST** - Before taking ANY screenshot: + ``` + mcp__chrome-devtools__resize_page: + width: 1280 + height: 640 (or taller if content needs it) + ``` + +2. **Image format:** + - PNG only + - 1280px width (never vary) + - Height: 640px or taller if needed + - Light mode only + +3. **File location:** + - Save in same directory as the markdown file + - Use kebab-case names: `prevention-dashboard-overview.png` + +4. **Markdown syntax:** + - Use `![descriptive alt text](./image-name.png)` + - NOT `` tags (except when size specification needed) + +## Workflow Steps + +### 1. Identify What to Capture + +Ask the user: +- Which page needs screenshots? +- What specific views or features to capture? +- Are there any specific states to show? (expanded menus, filled forms, etc.) + +### 2. Navigate to the Page + +``` +mcp__chrome-devtools__navigate_page: + type: url + url: https://demo.cloud.turbot-dev.com/apollo/[path] +``` + +Wait for page to fully load using `wait_for` if needed. + +### 3. Prepare the Viewport + +**CRITICAL STEP - Do this before EVERY screenshot:** + +``` +mcp__chrome-devtools__resize_page: + width: 1280 + height: 640 +``` + +**Adjust height if needed:** +- If content is tall, use height: 800, 1000, or higher +- ALWAYS keep width at 1280px +- Taller screenshots are fine when necessary + +### 4. Set Up the View + +- Scroll to show relevant content +- Expand sections if needed (`click` tool) +- Wait for animations/loading (`wait_for` tool) +- Ensure meaningful content is visible (not empty states) + +### 5. Take the Screenshot + +``` +mcp__chrome-devtools__take_screenshot: + filePath: /Users/jsmyth/src/guardrails-docs/docs/[section]/[page]/[name].png + format: png +``` + +**File path examples:** +- `/Users/jsmyth/src/guardrails-docs/docs/prevention/dashboard/dashboard-overview.png` +- `/Users/jsmyth/src/guardrails-docs/docs/prevention/objectives/benchmarks/benchmarks-list.png` + +### 6. Add to Documentation + +Insert the image in the markdown file using relative path: + +```markdown +![Descriptive alt text explaining what the image shows](./image-name.png) +``` + +**Alt text guidelines:** +- Describe what's shown: "Prevention Dashboard showing overall scores and account list" +- Not: "Screenshot" or "Image of dashboard" +- Be specific and helpful for screen readers + +### 7. Repeat for Additional Screenshots + +For each new screenshot: +1. Navigate/scroll to new view +2. **Resize viewport again** (width: 1280, appropriate height) +3. Take screenshot +4. Add to documentation + +### 8. Verify + +Check: +- [ ] All screenshots are 1280px wide +- [ ] Screenshots show meaningful content +- [ ] Saved in same directory as markdown file +- [ ] Use relative paths `./image.png` +- [ ] Use markdown syntax `![alt](./image.png)` +- [ ] Alt text is descriptive and specific +- [ ] Light mode used for all screenshots +- [ ] File names use kebab-case + +## Common Scenarios + +### Full-Page Screenshot +``` +# Resize viewport +resize_page: width 1280, height 640 + +# Capture +take_screenshot: fullPage false (captures viewport) +``` + +### Tall Content +``` +# Resize viewport with more height +resize_page: width 1280, height 1200 + +# Capture +take_screenshot: fullPage false +``` + +### Specific Element (Modal/Dialog) +``` +# Resize viewport +resize_page: width 1280, height 640 + +# Find element and capture just that +take_screenshot: uid [element-uid] +``` + +### Multiple Views (Tabs/States) +``` +# For each view: +1. Navigate/click to show view +2. Resize viewport (1280 width) +3. Take screenshot +4. Add to docs with descriptive alt text +``` + +## Troubleshooting + +**Screenshots wrong size:** +- Did you resize viewport BEFORE taking screenshot? +- Did you use width: 1280? +- Did you resize AGAIN after navigating to new page? + +**Content cut off:** +- Increase height: 800, 1000, 1200, etc. +- Keep width at 1280px +- Take multiple screenshots if needed + +**Image not showing in docs:** +- Check file path is relative: `./image.png` not absolute +- Verify image is in same directory as markdown file +- Check file name uses kebab-case with .png extension + +## Example Complete Flow + +``` +1. User: "Add screenshots to the simulator page" + +2. Navigate to simulator: + navigate_page: url https://demo.cloud.turbot-dev.com/apollo/prevention/simulator + +3. Resize viewport: + resize_page: width 1280, height 640 + +4. Take overview screenshot: + take_screenshot: /Users/jsmyth/src/guardrails-docs/docs/prevention/simulator/simulator-overview.png + +5. Click to show SCP templates: + click: uid [templates-button] + +6. Resize again for new view: + resize_page: width 1280, height 800 + +7. Take templates screenshot: + take_screenshot: /Users/jsmyth/src/guardrails-docs/docs/prevention/simulator/scp-templates.png + +8. Add to markdown: + ![Simulator overview showing organization hierarchy](./simulator-overview.png) + ... + ![SCP template library showing pre-built policies](./scp-templates.png) +``` diff --git a/.claude/skills/docs/workflows/fix-links.md b/.claude/skills/docs/workflows/fix-links.md new file mode 100644 index 00000000..5816d74c --- /dev/null +++ b/.claude/skills/docs/workflows/fix-links.md @@ -0,0 +1,247 @@ +# Fix Links Workflow + +You are fixing link formatting issues in Turbot Guardrails documentation to match the project's standards. + +## Reference Context + +Review `../context/style.md` for complete link formatting rules. + +## Link Format Rules + +**MUST follow these exactly:** + +1. **Use absolute paths starting with `/guardrails`:** + - ✅ `[Dashboard](/guardrails/docs/prevention/dashboard)` + - ❌ `[Dashboard](./dashboard)` or `[Dashboard](dashboard.md)` + +2. **Omit file extensions:** + - ✅ `[Preventions](/guardrails/docs/prevention/preventions)` + - ❌ `[Preventions](/guardrails/docs/prevention/preventions.md)` + +3. **Omit `index.md` for directory pages:** + - ✅ `[Dashboard](/guardrails/docs/prevention/dashboard)` + - ❌ `[Dashboard](/guardrails/docs/prevention/dashboard/index)` + +4. **Include filename for non-index pages:** + - ✅ `[Explore](/guardrails/docs/prevention/dashboard/explore)` + - ✅ `[Detail](/guardrails/docs/prevention/preventions/detail)` + +5. **Link once per section maximum:** + - Don't repeat the same link multiple times in the same section + - Makes text unreadable with too many hyperlinks + +## Workflow Steps + +### 1. Identify the Scope + +Ask the user: +- Which file(s) need link fixes? +- Specific pages or entire directory? +- Any particular link issues they've noticed? + +### 2. Read the File(s) + +Use the Read tool to get the current content: + +``` +Read: /Users/jsmyth/src/guardrails-docs/docs/[section]/[page]/index.md +``` + +### 3. Identify Link Issues + +Common problems to look for: + +**Relative paths:** +```markdown +❌ [page](./page) +❌ [page](../other/page) +❌ [page](page.md) +``` + +**File extensions:** +```markdown +❌ [page](/guardrails/docs/section/page.md) +❌ [page](/guardrails/docs/section/index.md) +``` + +**Incorrect index references:** +```markdown +❌ [Dashboard](/guardrails/docs/prevention/dashboard/index) +``` + +**Repeated links in same section:** +```markdown +## Section + +[Objectives](/guardrails/docs/prevention/objectives) are important. +You can view [Objectives](/guardrails/docs/prevention/objectives) in the UI. +The [Objectives](/guardrails/docs/prevention/objectives) page shows... +``` + +### 4. Fix Each Issue + +Use the Edit tool to fix links: + +**Fix relative paths to absolute:** +```markdown +# Before +[Explore](./explore) + +# After +[Explore](/guardrails/docs/prevention/dashboard/explore) +``` + +**Remove .md extensions:** +```markdown +# Before +[Preventions](/guardrails/docs/prevention/preventions.md) + +# After +[Preventions](/guardrails/docs/prevention/preventions) +``` + +**Remove index.md references:** +```markdown +# Before +[Dashboard](/guardrails/docs/prevention/dashboard/index) + +# After +[Dashboard](/guardrails/docs/prevention/dashboard) +``` + +**De-duplicate repeated links:** +Keep first occurrence, remove subsequent ones in same section: +```markdown +# Before +## Understanding Objectives + +[Objectives](/guardrails/docs/prevention/objectives) help you track security goals. +The [Objectives](/guardrails/docs/prevention/objectives) page shows your progress. +Click [Objectives](/guardrails/docs/prevention/objectives) to see details. + +# After +## Understanding Objectives + +[Objectives](/guardrails/docs/prevention/objectives) help you track security goals. +The Objectives page shows your progress. +Click Objectives to see details. +``` + +### 5. Determine Correct Paths + +To construct the correct path: + +1. Start with `/guardrails/docs/` +2. Add section: `prevention/`, `guides/`, `concepts/`, etc. +3. Add subsection(s): `dashboard/`, `objectives/`, etc. +4. For directory index: stop there +5. For specific page: add filename without .md + +**Examples:** +``` +Directory index: +- File: docs/prevention/dashboard/index.md +- Link: /guardrails/docs/prevention/dashboard + +Specific page: +- File: docs/prevention/dashboard/explore/index.md +- Link: /guardrails/docs/prevention/dashboard/explore + +Detail page: +- File: docs/prevention/objectives/objective-detail/index.md +- Link: /guardrails/docs/prevention/objectives/objective-detail +``` + +### 6. Verify Fixed Links + +Check each fixed link: +- [ ] Starts with `/guardrails/docs/` +- [ ] No `.md` extension +- [ ] No `index` or `index.md` +- [ ] Path matches file structure +- [ ] Not repeated in same section + +### 7. Test (if possible) + +If you can test: +- Click links to verify they work +- Check that anchor links (`#heading`) work +- Verify external links open correctly + +## Common Patterns + +### Prevention Section Links + +```markdown +✅ [Dashboard](/guardrails/docs/prevention/dashboard) +✅ [Objectives](/guardrails/docs/prevention/objectives) +✅ [Benchmarks](/guardrails/docs/prevention/objectives/benchmarks) +✅ [Priorities](/guardrails/docs/prevention/objectives/priorities) +✅ [Preventions](/guardrails/docs/prevention/preventions) +✅ [Types](/guardrails/docs/prevention/preventions/types) +✅ [Recommendations](/guardrails/docs/prevention/objectives/recommendations) +✅ [Simulator](/guardrails/docs/prevention/simulator) +``` + +### Guides Section Links + +```markdown +✅ [AWS Guides](/guardrails/docs/guides/aws) +✅ [Azure Guides](/guardrails/docs/guides/azure) +✅ [GCP Guides](/guardrails/docs/guides/gcp) +``` + +### Concepts Section Links + +```markdown +✅ [Controls](/guardrails/docs/concepts/controls) +✅ [Policies](/guardrails/docs/concepts/policies) +✅ [Resources](/guardrails/docs/concepts/resources) +``` + +## Batch Fixing + +If fixing multiple files: + +1. Read all files first +2. Create a fix plan +3. Show user what will change +4. Fix one file at a time using Edit tool +5. Verify each fix before moving to next + +## Report Changes + +After fixing, summarize for the user: +- How many files were updated +- Types of issues fixed (relative paths, extensions, duplicates) +- Any issues that couldn't be fixed automatically +- Suggestions for prevention + +## Example Complete Flow + +``` +1. User: "Fix all links in the prevention objectives folder" + +2. Read files: + - docs/prevention/objectives/index.md + - docs/prevention/objectives/benchmarks/index.md + - docs/prevention/objectives/priorities/index.md + - etc. + +3. Identify issues: + - benchmarks/index.md has relative link: [Objectives](../objectives) + - priorities/index.md has .md extension: [Categories](/guardrails/docs/prevention/objectives/categories.md) + - objectives/index.md repeats link 3 times in same section + +4. Fix issues: + - Edit benchmarks/index.md: change to [Objectives](/guardrails/docs/prevention/objectives) + - Edit priorities/index.md: remove .md extension + - Edit objectives/index.md: keep first link, remove duplicates + +5. Report: + - Fixed 3 files + - Corrected 1 relative path + - Removed 1 file extension + - De-duplicated 2 links + - All links now follow project standards +``` diff --git a/.claude/skills/docs/workflows/new-page.md b/.claude/skills/docs/workflows/new-page.md new file mode 100644 index 00000000..ea467f72 --- /dev/null +++ b/.claude/skills/docs/workflows/new-page.md @@ -0,0 +1,147 @@ +# Create New Documentation Page Workflow + +You are creating a new documentation page for Turbot Guardrails following the project's standards. + +## Reference Context + +Before starting, review: +- `../context/style.md` for formatting rules +- `../context/prevention.md` if working on prevention docs + +## Workflow Steps + +### 1. Understand the Requirements + +Ask the user: +- What is the page about? (topic/feature) +- Where should it live in the docs structure? +- Is this for the prevention section or another area? +- Do they have any existing content or should you explore the feature first? + +### 2. Create Folder Structure + +Each page needs its own folder with `index.md`: + +```bash +# Create folder +mkdir -p docs/[section]/[page-name]/ + +# Example: +mkdir -p docs/prevention/dashboard/explore/ +``` + +### 3. Explore the Feature (if needed) + +If documenting an existing feature: +- Navigate to the application using Chrome DevTools MCP +- Take notes on key functionality +- Identify what screenshots will be helpful +- Understand the user workflows and use cases + +### 4. Write the Page + +Create `index.md` with this structure: + +```yaml +--- +title: Page Title +sidebar_label: Page Title +--- + +# Page Title + +Opening paragraph(s) explaining what this is and why it matters. +Write conversationally, focus on value and use cases. + +## First Major Concept + +Explain with examples and context... + +## Second Major Concept + +More explanation... + +## Common Use Cases + +Practical scenarios showing how users accomplish goals... + +## Next Steps + +- [Related page 1](/guardrails/docs/section/page1) +- [Related page 2](/guardrails/docs/section/page2) +``` + +**Critical rules:** +- One h1 matching frontmatter title exactly +- NO `## Overview` header - start content immediately +- Use h2 for all subsequent headers +- Write in second person (you) +- Explain WHY features matter, not just WHAT they do +- Include practical use cases and examples + +### 5. Add Screenshots + +If screenshots are needed: +- Invoke the `add-screenshots` workflow +- Or manually: resize viewport to 1280px width, capture, save to same directory + +### 6. Update Sidebar + +Add the new page to `docs/sidebar.json`: + +```json +{ + "type": "category", + "id": "section/parent", + "items": [ + "section/existing-page", + "section/new-page" // Add here + ] +} +``` + +**Ordering:** +- Detail pages appear immediately after their list page +- Group related pages together +- Use same labels as tab names in UI + +### 7. Validate + +Check: +- [ ] Folder structure: `docs/section/page-name/index.md` +- [ ] Frontmatter present with matching title/sidebar_label +- [ ] Single h1 matching frontmatter +- [ ] No `## Overview` header +- [ ] Conversational tone explaining value, not just describing UI +- [ ] Links use absolute paths `/guardrails/docs/...` +- [ ] Links omit `.md` and `index.md` +- [ ] Screenshots in same directory with relative paths `./image.png` +- [ ] Screenshots use markdown syntax `![alt](./image.png)` +- [ ] Added to sidebar.json + +## Prevention-Specific Guidelines + +If documenting prevention features: +- Explain security concepts, not just UI elements +- Address common workflows: finding gaps, prioritizing work, verifying coverage +- Explain relationships: Objectives vs Preventions, Layers, Types, Categories +- Use concrete examples: EBS encryption, S3 public access, SCPs +- Emphasize prevention-first approach (stop issues before they reach production) +- Avoid exhaustive "Page Layout" bullet lists +- Write in flowing prose, use bullets sparingly + +## Example Outcomes + +**Good:** +- Conversational tone that engages readers +- Explains why features exist and how to use them +- Includes practical scenarios and workflows +- Images show meaningful content +- Links are correct and non-repetitive + +**Bad:** +- Dry bullet lists of every UI element +- Missing the "why" - just describes what's on screen +- Templated/repetitive structure +- Broken or incorrect link formats +- Missing or incorrectly formatted images diff --git a/.claude/skills/docs/workflows/review.md b/.claude/skills/docs/workflows/review.md new file mode 100644 index 00000000..59afa05a --- /dev/null +++ b/.claude/skills/docs/workflows/review.md @@ -0,0 +1,314 @@ +# Review Documentation Workflow + +You are reviewing Turbot Guardrails documentation to ensure it follows the project's style guidelines and best practices. + +## Reference Context + +Review both context files before starting: +- `../context/style.md` for formatting and structure rules +- `../context/prevention.md` if reviewing prevention documentation + +## Review Checklist + +### Structure & Formatting + +- [ ] **Frontmatter present and correct:** + ```yaml + --- + title: Page Title + sidebar_label: Page Title + --- + ``` + +- [ ] **Single h1 matching frontmatter exactly:** + - One h1 per page: `# Page Title` + - Matches `title` and `sidebar_label` + +- [ ] **No `## Overview` header:** + - Content starts immediately after h1 + - First paragraphs explain what/why without a header + +- [ ] **Headers use proper hierarchy:** + - H1 for page title only + - H2 for main sections + - H3 for subsections + - All use Title Case + +### Images + +- [ ] **Images use markdown syntax:** + - ✅ `![alt text](./image.png)` + - ❌ `` (unless size needed) + +- [ ] **Images stored in same directory:** + - Not in `/images/` directory + - Use relative paths: `./image-name.png` + +- [ ] **Alt text is descriptive:** + - Explains what's shown + - Not just "screenshot" or "image" + +- [ ] **Screenshot specifications met:** + - PNG format + - 1280px width (height can vary) + - Light mode + - No browser chrome + - Meaningful content (not empty states) + +### Links + +- [ ] **Links use absolute paths:** + - ✅ `[Page](/guardrails/docs/section/page)` + - ❌ `[Page](./page)` or `[Page](../section/page)` + +- [ ] **No file extensions:** + - ✅ `/guardrails/docs/prevention/dashboard` + - ❌ `/guardrails/docs/prevention/dashboard.md` + +- [ ] **No index.md references:** + - ✅ `/guardrails/docs/prevention/dashboard` + - ❌ `/guardrails/docs/prevention/dashboard/index` + +- [ ] **Links not repeated in same section:** + - Link on first mention only + - Subsequent mentions use plain text + +### File Organization + +- [ ] **Page in its own folder:** + - Path: `docs/section/page-name/index.md` + - Not: `docs/section/page-name.md` + +- [ ] **Images in same folder:** + - `docs/section/page-name/index.md` + - `docs/section/page-name/image.png` + +- [ ] **Folder/file names use kebab-case:** + - ✅ `prevention-dashboard.png` + - ❌ `prevention_dashboard.png` or `preventionDashboard.png` + +### Writing Style + +- [ ] **Conversational tone:** + - Writes naturally, explains WHY + - Not dry/robotic reference style + +- [ ] **Second person voice:** + - Uses "you" + - Exception: "let's" in tutorials + +- [ ] **Explains value and purpose:** + - Not just describing UI + - Shows how features help accomplish goals + +- [ ] **Includes practical examples:** + - Real scenarios + - Common use cases + - Concrete examples (not abstract) + +- [ ] **Appropriate use of lists:** + - Prose paragraphs for explanation + - Bullets for actual lists + - Not bullet-heavy "Page Layout" sections + +### Code & UI Elements + +- [ ] **UI elements are bolded:** + - ✅ Click the **Launch** button + - ❌ Click the Launch button + +- [ ] **Code/values use backticks:** + - ✅ Enter `my-volume` in the field + - ✅ Use the `--region` flag + +- [ ] **Code blocks specify language:** + ```bash + # Good + ``` + + ``` + # Bad - no language specified + ``` + +### Prevention-Specific (if applicable) + +- [ ] **Explains security concepts:** + - Not just UI descriptions + - Explains relationships (Objectives vs Preventions) + +- [ ] **Addresses common workflows:** + - Finding gaps + - Prioritizing work + - Verifying coverage + - Testing controls + +- [ ] **Uses concrete examples:** + - EBS encryption + - S3 public access + - Service Control Policies + +- [ ] **Emphasizes prevention-first:** + - Stop issues before they reach production + - Not just detection + +- [ ] **Avoids exhaustive UI listings:** + - No bullet lists of every field + - Explains capabilities, not just enumerates + +## Workflow Steps + +### 1. Identify Scope + +Ask the user: +- Which file(s) to review? +- Looking for specific issues or comprehensive review? +- Should you fix issues or just report them? + +### 2. Read the File(s) + +Use Read tool to get content: +``` +Read: /Users/jsmyth/src/guardrails-docs/docs/[section]/[page]/index.md +``` + +### 3. Review Against Checklist + +Go through each category systematically: +1. Structure & Formatting +2. Images +3. Links +4. File Organization +5. Writing Style +6. Code & UI Elements +7. Prevention-Specific (if applicable) + +### 4. Document Findings + +Create a report with sections: + +**Compliant Items:** +- List what follows guidelines correctly + +**Issues Found:** +- List each issue with location (line number) +- Categorize by severity: Critical, Important, Minor +- Show incorrect example and correct fix + +**Recommendations:** +- Suggestions for improvement +- Not violations but enhancements + +### 5. Fix or Report + +Based on user preference: + +**Option A - Fix Issues:** +- Use Edit tool to fix each issue +- Make one edit at a time +- Verify each fix + +**Option B - Report Only:** +- Provide detailed report +- Let user decide what to fix +- Offer to fix if they want + +### 6. Summary + +Provide: +- Total issues found by category +- What was fixed (if applicable) +- Remaining issues (if any) +- Overall assessment (excellent, good, needs work) + +## Issue Severity Levels + +**Critical (must fix):** +- Broken image/link paths +- Missing frontmatter +- Wrong folder structure +- HTML `` tags without reason + +**Important (should fix):** +- Relative link paths +- `.md` extensions in links +- Repeated links in same section +- Missing alt text on images +- `## Overview` header present + +**Minor (nice to fix):** +- Inconsistent capitalization +- Could improve alt text descriptions +- Writing could be more conversational +- Missing some contextual examples + +## Example Report Format + +```markdown +# Documentation Review: [Page Name] + +## Summary +Reviewed: docs/prevention/objectives/index.md +Overall: Good - minor improvements needed +Issues found: 3 Important, 2 Minor + +## Compliant Areas ✅ +- Proper frontmatter and h1 structure +- Images use markdown syntax and relative paths +- Conversational tone with good examples +- No exhaustive UI bullet lists + +## Issues Found + +### Important Issues +1. **Line 45**: Link uses relative path + - Current: `[Preventions](../preventions)` + - Fix: `[Preventions](/guardrails/docs/prevention/preventions)` + +2. **Line 67**: Link includes .md extension + - Current: `[Dashboard](/guardrails/docs/prevention/dashboard.md)` + - Fix: `[Dashboard](/guardrails/docs/prevention/dashboard)` + +3. **Line 89**: Link repeated 3 times in same section + - Keep first occurrence only + - Remove repetitions on lines 92, 97 + +### Minor Issues +1. **Line 23**: Alt text could be more descriptive + - Current: `![Screenshot](./objectives.png)` + - Suggestion: `![Objectives view showing priority levels and scores](./objectives.png)` + +2. **Line 134**: Could add concrete example + - Add real scenario like EBS encryption requirement + +## Recommendations +- Consider adding a "Common Use Cases" section +- Some paragraphs could explain "why" more deeply +- Screenshot at line 56 could show expanded view for clarity + +## Next Steps +Would you like me to: +1. Fix all Important issues automatically +2. Fix specific issues only +3. Leave as-is and you'll fix manually +``` + +## Quick Review Mode + +For fast checks, focus on critical items: +1. Frontmatter present? +2. Images and links working? +3. Folder structure correct? +4. Any obvious style violations? + +Report: "Quick check: [Pass/Fail] with [N] issues needing attention" + +## Comprehensive Review Mode + +For thorough reviews: +1. Check every item on the full checklist +2. Read for tone and clarity +3. Verify all technical accuracy +4. Check consistency with similar pages +5. Provide detailed improvement suggestions + +Report: Full formatted report with all sections diff --git a/.gitignore b/.gitignore index 1c60cada..7d426095 100644 --- a/.gitignore +++ b/.gitignore @@ -130,6 +130,10 @@ dist .pnp.* .DS_Store +# vscode +.vscode/ + + docs/mods/aws docs/mods/azure docs/mods/turbot @@ -138,4 +142,4 @@ docs/mods/servicenow docs/mods/osquery docs/mods/kubernetes docs/reference/graphql -sidebar-generated.json \ No newline at end of file +sidebar-generated.json diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..a5baa7d1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,288 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Overview + +This is the documentation repository for Turbot Guardrails, a cloud governance and security compliance platform. The docs cover multi-cloud support (AWS, Azure, GCP, GitHub, Kubernetes) and are organized into Getting Started guides, core Concepts, procedural Guides, Developer documentation, Reference material, and FAQ sections. + +## Documentation System Architecture + +This uses a **custom Markdown-based documentation system** (not Docusaurus, Mintlify, or Gatsby): +- Markdown files in `docs/` folder with YAML frontmatter +- Custom sidebar navigation defined in JSON files +- Deployed via **Vercel** with CI/CD through GitHub Actions +- Images stored in `/images/` folder + +### Document Structure Requirements + +Each Markdown document requires frontmatter: +```yaml +--- +title: Page Title +sidebar_label: Navigation Label +--- +``` + +- Supports up to 2 levels of nesting (e.g., `docs/foo/bar/`) +- Entry-point document contains `slug: /` +- Images must be referenced using HTML tags: `` + +## Navigation & Sidebar Configuration + +Navigation is defined through a hierarchical JSON sidebar system: + +- **Main sidebar**: `docs/sidebar.json` - Primary navigation hub +- **Generated sidebar**: `docs/sidebar-generated.json` - Auto-processed with enriched metadata +- **Modular sidebars**: Cloud/feature-specific sidebars referenced via "placeholder" type entries: + - `docs/guides/aws/aws-sidebar.json` + - `docs/guides/azure/azure-sidebar.json` + - `docs/guides/gcp/gcp-sidebar.json` + - `docs/guides/github/github-sidebar.json` + - `docs/guides/using-guardrails/ai/ai-sidebar.json` + - `docs/guides/using-guardrails/stacks/stack-sidebar.json` + - `docs/developers/developers-sidebar.json` + +### Sidebar Entry Types + +- `"category"` - Groups documents with nested "items" array +- `"placeholder"` - Includes external sidebar JSON files for modularization +- `"external"` - Links to external sites (Hub, Changelog) +- Supports `"link"` attribute for custom URLs +- Uses `"id"` for unique identification + +## Deployment Workflows + +### Production Deployment +- **Workflow**: `.github/workflows/deploy.yml` +- **Trigger**: Pushes to `main` branch or manual dispatch +- **Action**: Triggers Vercel webhook via `secrets.VERCEL_DEPLOY_LINK_PROD` + +### Preview Builds +- **Workflow**: `.github/workflows/trigger-turbot-com.yml` +- **Trigger**: Pull requests and feature branches (non-main) +- **Action**: + - Sends repository dispatch event to `turbot/turbot.com` repo + - Fetches deployment details from Tailpipe API + - Posts preview link as PR comment with commit info +- **Preview branch pattern**: `docs/guardrails/{branch-name}` + +## Content Organization + +Documentation is organized into **8 major sections**: + +1. **Getting Started** (`getting-started/`) + - 7-minute labs for quick tutorials + - Cloud-specific setup (AWS, Azure, GCP) + - Organization and user setup + +2. **Prevention** (`prevention/`) + - Dashboard, accounts, objectives + - Prevention configuration and simulator + +3. **Concepts** (`concepts/`) + - Activities, Controls, Guardrails (with tagging subcategory) + - IAM, Policies, Policy Packs, Processes, Resources + +4. **Guides** (`guides/`) + - Cloud provider-specific guides (AWS, Azure, GCP, GitHub, Kubernetes) + - Feature guides (configuring/using/hosting guardrails) + - ServiceNow integration + - Troubleshooting + +5. **FAQ** (`faq/`) + - Organized by cloud provider and general topics + +6. **Developers** (`developers/`) + - Policy pack development + - MCP installation, GraphQL, Nunjucks + - Debugging guides + +7. **Reference** (`reference/`) + - CLI commands and installation + - Terraform setup + - Filter language, OCL, GraphQL schema + - Glossary and samples repo + +8. **External Links** + - Hub and Changelog (external sites) + +## Contributing Guidelines + +Per README.md: +- Fork repository and work from `main` branch +- Create pull requests with clear, descriptive commit messages +- Check existing open PRs before starting work +- Create an issue for significant contributions before starting +- Contributors must sign Contributor License Agreement (CLA) +- Published under CC BY-NC-ND license + +### Issue Templates + +Available in `.github/ISSUE_TEMPLATE/`: +- `new-guide--create-new-guide.md` - For proposing new guides +- `update-guide--update-guide.md` - For updating existing guides + +## Key Files & Locations + +- `docs/sidebar.json` - Main navigation configuration +- `docs/index.md` - Homepage (slug: `/`) +- `.github/workflows/trigger-turbot-com.yml` - Preview build orchestration +- `.github/workflows/deploy.yml` - Production deployment +- `/images/` - All image assets +- `README.md` - Contribution guidelines and documentation format + +## Multi-Cloud Support + +The documentation extensively covers: +- **AWS** - Account setup, IAM, services, best practices +- **Azure** - Subscription setup, management groups, resources +- **GCP** - Project setup, organization policies, resources +- **GitHub** - Repository management and integrations +- **Kubernetes** - Cluster governance + +Cloud-specific content is organized both by provider (in guides/) and by cross-cloud concepts (in concepts/). + +## Prevention Documentation Terminology + +The prevention documentation (`docs/prevention/`) uses specific terminology to avoid confusion with Guardrails product features: + +### Key Terms + +- **Prevention** (noun): A preventive mechanism like an SCP, Azure Policy, account setting, or GitHub ruleset that stops security issues before they occur +- **Preventive mechanism**: Technical implementation of a prevention (use when emphasizing the "how") +- **Objective**: A security goal or requirement (the "what" you're trying to achieve) +- **Layer**: When a prevention operates (Build, Access, Config, Runtime) +- **Guardrails Control** (capitalize Control): The specific product feature that enforces Guardrails policies with states (OK, Alarm, Error, etc.) - documented in `/docs/concepts/controls` + +### What NOT to call preventions + +- ❌ "control" (generic) - conflicts with Guardrails Controls +- ❌ "security control" (generic) - use "prevention" instead +- ✅ "Service Control Policy" (specific AWS term) - keep as-is +- ✅ "control" (verb) - fine to use as a verb (e.g., "controls network traffic") + +### When editing prevention docs + +- Replace generic "control(s)" with "prevention(s)" +- Preserve "Service Control Policy" (official AWS term) +- Preserve "Guardrails control(s)" when specifically referring to the Controls feature +- Preserve "control" as a verb + +## Multi-Step Task Management + +When working on tasks that span multiple files or require multiple steps, use the TodoWrite tool to track progress. + +### Best Practices + +**For multi-file changes:** +- Create one todo item per logical unit of work (usually one file or related group) +- Mark items as in_progress BEFORE starting work +- Mark as completed IMMEDIATELY after finishing (don't batch) +- Keep exactly ONE item in_progress at a time + +**For terminology changes:** +- First todo: "Analyze uses of [term] in [directory]" +- Second todo: "Propose alternative terminology" +- Remaining todos: One per file or logical group to update +- Final todo: "Verify and commit changes" + +**For section standardization:** +- First todo: "Identify section title variants" +- Middle todos: One per file to update +- Final todo: "Format existing sections with new standard" + +**Progress visibility:** +- User can see the todo list state +- Update frequently to show progress +- Clear, specific todo descriptions +- Active form should be present continuous tense (e.g., "Updating X" not "Update X") + +## Common Documentation Patterns + +### Parent-Child Page Structure + +Parent pages (index.md) should be **overviews with links**, not detailed content: +- Brief introduction (2-3 paragraphs) +- "Available Views" or "Available Options" section with links to children +- "Understanding [Topic]" section with high-level concepts +- "Next Steps" with links to related pages + +Child pages should contain **detailed content**: +- Comprehensive explanations +- Screenshots and examples +- "Common Use Cases" section +- "Next Steps" linking back to parent or siblings + +**Example**: `prevention/preventions/index.md` (overview) vs `prevention/preventions/preventions/index.md` (details) + +### Common Use Cases Section Format + +Standard format across all pages: +```markdown +## Common Use Cases + +- **When [scenario description]** - Detailed explanation of what to do, why it matters, and what outcome to expect. May include specific examples or commands. + +- **When [another scenario]** - More details about this use case. +``` + +Key characteristics: +- Bullet list (not paragraphs) +- Bold scenario name starting with "When" +- Dash separator +- 2-4 sentences of explanation +- Specific and actionable + +### Detail Page Structure + +Most detail pages follow this pattern: +1. Title and introduction +2. "What You're Looking At" or "Understanding [Topic]" +3. Main content sections +4. "Common Use Cases" +5. "Next Steps" + +Detail pages may have subsections like: +- "[Feature] Detail View" for drilling into specifics +- "Using the [Feature]" for interaction guidance +- "Best Practices" for recommendations + +### Organizing Documentation by UI Flow + +When documenting features with multiple options or methods, organize content in the order users encounter them in the interface, not by importance or frequency of use. + +**Why**: This reduces cognitive load - users can follow along with the documentation while looking at the actual interface without having to mentally reorder information. + +**Example**: When documenting a dialog with tabs (File Upload, Mock Events, Manual Entry), document them in that left-to-right tab order even if Mock Events is the most commonly used option. + +### Interactive Feature Documentation + +When documenting interactive features (dialogs, forms, wizards), use a three-part screenshot approach: + +1. **Overview screenshot** - Show the feature in use with data/results visible +2. **Interaction screenshots** - Show how to use the feature (opening dialogs, selecting options, filling forms) +3. **Result screenshots** - Show outcomes and what happens after interaction + +**Example structure**: +```markdown +### Feature Name + +Feature does X and Y. + +![Feature with results visible](./feature-overview.png) + +#### Using the Feature + +Click "Action" to open the dialog... + +![Dialog showing options](./feature-dialog.png) + +Select an option to... + +![Selected option with populated fields](./feature-selected.png) + +After completing the action, results appear in... +``` + +This pattern helps users understand both what the feature does (overview) and how to use it (step-by-step), making documentation more actionable. diff --git a/docs/concepts/index.md b/docs/concepts/index.md index b30a8aad..d0c295e5 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -1,8 +1,8 @@ --- -title: Concepts +title: Guardrails --- -# Concepts +# Guardrails Concepts Turbot Guardrails provides enterprise guardrails for infrastructure platforms, including Amazon Web Services, Microsoft Azure, and Google Cloud. diff --git a/docs/prevention/accounts/accounts-list-loaded.png b/docs/prevention/accounts/accounts-list-loaded.png new file mode 100644 index 00000000..158b732d Binary files /dev/null and b/docs/prevention/accounts/accounts-list-loaded.png differ diff --git a/docs/prevention/accounts/accounts/account-detail-prevention.png b/docs/prevention/accounts/accounts/account-detail-prevention.png new file mode 100644 index 00000000..d56ca83f Binary files /dev/null and b/docs/prevention/accounts/accounts/account-detail-prevention.png differ diff --git a/docs/prevention/accounts/accounts/accounts-filter-panel.png b/docs/prevention/accounts/accounts/accounts-filter-panel.png new file mode 100644 index 00000000..ff17e362 Binary files /dev/null and b/docs/prevention/accounts/accounts/accounts-filter-panel.png differ diff --git a/docs/prevention/accounts/accounts/accounts-list-loaded.png b/docs/prevention/accounts/accounts/accounts-list-loaded.png new file mode 100644 index 00000000..01e48f3f Binary files /dev/null and b/docs/prevention/accounts/accounts/accounts-list-loaded.png differ diff --git a/docs/prevention/accounts/accounts/index.md b/docs/prevention/accounts/accounts/index.md new file mode 100644 index 00000000..66afa741 --- /dev/null +++ b/docs/prevention/accounts/accounts/index.md @@ -0,0 +1,67 @@ +--- +title: Accounts +sidebar_label: Accounts +--- + +# Accounts + +The Accounts tab provides a flat list view of all cloud accounts, subscriptions, and repositories managed by Turbot Guardrails. Use this view to search, filter, and sort accounts to quickly find those needing attention. + +![Accounts List](./accounts-list-loaded.png) + +## Understanding the Accounts List + +The Accounts list shows all your cloud accounts, subscriptions, and repositories in one place—AWS accounts (12-digit numbers), Azure subscriptions, GCP projects, and GitHub repositories. Each row shows the account name and ID, which organizational folder or OU it belongs to, its prevention score (0-5 indicating how well it's protected), active alerts, and how many controls are running. + +This is your starting point for understanding prevention coverage across your environment. You can quickly spot accounts with weak protection by sorting by score, filter to specific cloud providers to check consistency, or search for specific accounts you're investigating. The view adapts to how you work—whether you're hunting for gaps, tracking compliance across accounts, or responding to alerts. + +## Finding What You Need + +Use the **Search** box to filter results with plain text search. Enter a search string and press Enter. + +Click the **Filter** button to show and hide the Filter panel. Filtering lets you narrow to specific cloud providers (AWS, Azure, GCP, GitHub), Turbot Guardrails folders, or resource tags. Sorting changes how accounts are ordered—alphabetically by default, but you can sort by score to find gaps (Low to High shows weakest protection first), by newest/oldest to see recently added accounts, or by updated recently to see where changes happened. + +![Filter panel showing cloud provider and folder options](./accounts-filter-panel.png) + +The Sort dropdown includes "Score (Low to High)" which is particularly useful for finding accounts needing attention. Accounts with scores below 3 often have significant gaps in prevention coverage. + +## Understanding Prevention Scores + +[Prevention scores](/guardrails/docs/prevention#prevention-scores) run from 0 to 5. Low scores (0-2) indicate minimal prevention coverage with significant gaps. Moderate scores (3) show basic protections but noticeable gaps. Good scores (4) reflect solid implementation. High scores (5) demonstrate comprehensive, defense-in-depth protection. + +Account scores aggregate all prevention objectives weighted by priority. A low score might mean missing critical P1 controls or lack of coverage across many objectives. Click into an account to see which specific objectives aren't being met and what recommendations exist to improve the score. + +## Account Detail View + +Clicking any account name opens the Account Detail page, which provides an in-depth view of prevention coverage for that single cloud account, subscription, or repository. This page breaks down the overall prevention score into specific categories, benchmarks, and recommendations, helping you understand exactly which preventions are implemented and which gaps need to be addressed. + +![Account Prevention Detail Page showing scores and recommendations](./account-detail-prevention.png) + +The Account Detail page shows: + +**[Overall Maturity](/guardrails/docs/prevention#prevention-scores)** - Your prevention score as a shield icon with the number, plus total objectives and preventions evaluated. This gives you a quick sense of how well-protected this account is. + +**[Benchmarks](/guardrails/docs/prevention/objectives/benchmarks)** - How this account scores against compliance frameworks—AWS CIS v6.0.0, Azure CIS v5.0.0, GCP CIS v3.0.0, GitHub CIS v1.1.0, and P1 Preventions benchmarks. A score of 5 means full compliance while scores of 0-2 signal significant gaps. + +**[Recommendations](/guardrails/docs/prevention/objectives/recommendations)** - Actionable guidance for improving this account's protection. Each recommendation shows what needs to be implemented, its priority level (P1 through P4), and the security impact you'll get. Click any recommendation to see detailed implementation guidance including step-by-step instructions and policy templates. + +**[Categories](/guardrails/docs/prevention/objectives/categories)** - Preventions organized by security domain—Identity & Access, Data Governance, Trust & Sharing, Network Perimeter, Core Infrastructure, Audit & Logging, and Feature Restrictions. This helps you spot imbalances—if Identity & Access scores 4.5 but Data Governance scores 1.5, you know where to focus improvement efforts. + +**[Layers](/guardrails/docs/prevention/preventions/layers)** - Coverage across different enforcement timing—Build (stop risky configurations before deployment), Access (control who can access resources), Config (enforce required configurations), and Runtime (detect and respond to risky behavior). Balanced coverage across layers provides better protection than perfect coverage at a single layer. + +## Common Use Cases + +- **When finding accounts with weak prevention coverage** - Sort by Score (Low to High) and review accounts below 3. Click into each one to see which objectives aren't met and implement the recommended preventions. This is especially important for production accounts where gaps represent real risk. + +- **When reviewing accounts by cloud provider** - Filter to AWS, Azure, or GCP and scan the prevention scores. If some accounts score 4.5 but others score 2.0, you have inconsistent protection—likely because preventions were implemented in some accounts but not others. This inconsistency often happens when accounts were created at different times or by different teams without standardized baselines. + +- **When you see non-zero alert counts** - Click the alert number to view details. Alerts indicate controls in alarm state—configurations that violate policies or drift from desired state. Taking corrective action based on alert severity keeps your environment compliant with the preventive controls you've defined. + +- **When improving an account's prevention score** - Open the Account Detail page, check the Overall Maturity score to understand current state, then review Recommendations for prioritized actions. Start with P1 recommendations and implement them using the detailed guidance provided. Return to this page after implementation to verify the score improves. + +## Next Steps + +- Use the [Organizations](/guardrails/docs/prevention/accounts/organizations) view to see account hierarchy +- Use the [Folders](/guardrails/docs/prevention/accounts/folders) view to analyze accounts by logical grouping +- Use the [Visualize](/guardrails/docs/prevention/accounts/visualize) view for a graphical representation +- Review [Recommendations](/guardrails/docs/prevention/objectives/recommendations) to prioritize prevention work diff --git a/docs/prevention/accounts/folders/folders-list.png b/docs/prevention/accounts/folders/folders-list.png new file mode 100644 index 00000000..9e193a95 Binary files /dev/null and b/docs/prevention/accounts/folders/folders-list.png differ diff --git a/docs/prevention/accounts/folders/index.md b/docs/prevention/accounts/folders/index.md new file mode 100644 index 00000000..0f8e8e1d --- /dev/null +++ b/docs/prevention/accounts/folders/index.md @@ -0,0 +1,37 @@ +--- +title: Folders +sidebar_label: Folders +--- + +# Folders + +The Folders view displays accounts organized by Turbot Guardrails folders—logical groupings that you define to organize resources across cloud providers. Unlike the Organizations view which shows cloud-native hierarchy, Folders represent your custom organizational structure within Guardrails. + +![Folders List](./folders-list.png) + +## Understanding the Folders View + +Folders are custom groupings you define in Turbot Guardrails to organize resources however makes sense for your organization—by team, environment, compliance scope, or any other criteria. Unlike the Organizations view (which shows cloud-native AWS/Azure/GCP hierarchy), Folders let you group resources from multiple cloud providers together. You can put AWS accounts, Azure subscriptions, and GCP projects in the same folder if they all belong to the same team or serve the same purpose. + +Each folder card shows the folder name, total alerts across all accounts in the folder, and how many accounts/subscriptions/repositories it contains. Click a folder to expand and see all nested accounts with their IDs, folder paths, alert counts, and control counts. This makes it easy to see everything belonging to a specific team or environment at a glance. + +Folders also support policy inheritance—you can apply Guardrails policies at the folder level and they affect all nested resources. This is powerful for ensuring consistent controls across accounts that share characteristics even if they're in different cloud providers or different parts of the cloud-native hierarchy. + +## Common Use Cases + +- **When organizing by team or business unit** - Create folders like Engineering (with dev/test/prod accounts), Data Science (with analytics accounts), or Security (with audit and logging accounts). This helps track prevention coverage by organizational ownership and makes it clear which team is responsible for each account. + +- **When organizing by environment** - Create a Production folder with all prod accounts across AWS, Azure, and GCP, a Non-Production folder with dev/test/staging, and a Sandbox folder for experimental work. This supports applying stricter preventions to production (enforcing encryption, blocking public access) while allowing more flexibility in non-production environments. + +- **When organizing for compliance** - Create folders based on regulatory scope—a PCI-DSS folder for accounts handling payment data, a HIPAA folder for healthcare-related accounts, or a Public folder for accounts with publicly accessible resources. This makes it easy to ensure accounts subject to specific regulations have the required preventive controls. + +## Folders vs Organizations + +The Organizations view shows cloud-native hierarchy (AWS Organizations, Azure Management Groups, GCP Org) as structured in the cloud provider—useful for understanding cloud-native policy inheritance like SCPs. The Folders view shows your custom Guardrails groupings, can include resources from multiple cloud providers in one folder, and supports Guardrails policy inheritance. Use Organizations when you need to understand cloud-native structure; use Folders when you need to organize by your internal organizational model. + +## Next Steps + +- Return to the [Accounts](/guardrails/docs/prevention/accounts) view for a flat list of all accounts +- Use the [Organizations](/guardrails/docs/prevention/accounts/organizations) view to see cloud-native hierarchy +- Use the [Visualize](/guardrails/docs/prevention/accounts/visualize) view for a graphical representation +- Click into any account to view detailed prevention scores by objective diff --git a/docs/prevention/accounts/index.md b/docs/prevention/accounts/index.md new file mode 100644 index 00000000..83a05257 --- /dev/null +++ b/docs/prevention/accounts/index.md @@ -0,0 +1,57 @@ +--- +title: Accounts +sidebar_label: Accounts +--- + +# Accounts + +The Accounts section provides multiple views of your cloud accounts, subscriptions, and repositories, helping you monitor prevention coverage across your multi-cloud environment. Each view offers a different perspective on the same data—choose the view that best fits your current task. + +![Accounts List](./accounts-list-loaded.png) + +## Available Views + +The Accounts section provides four different ways to view and analyze your cloud accounts: + +### Accounts Tab + +The [Accounts tab](/guardrails/docs/prevention/accounts/accounts) provides a flat list view with search, filter, and sort capabilities. This is your go-to view for finding specific accounts, identifying accounts with low prevention scores, or comparing prevention coverage across cloud providers. Each account shows its prevention score (0-5), active alerts, and organizational placement. + +Use this view when you need to quickly find accounts needing attention, compare prevention scores across your environment, or investigate specific accounts by name or ID. + +### Organizations Tab + +The [Organizations tab](/guardrails/docs/prevention/accounts/organizations) displays your cloud provider's native organizational structure—AWS Organizations with OUs, Azure Management Groups, or GCP resource hierarchy. This view helps you understand how organizational policies cascade down through the hierarchy and which accounts inherit which preventions. + +Use this view when you need to understand your cloud provider's organization structure, see how SCPs or Azure Policies apply to different organizational units, or identify accounts based on their position in the hierarchy. + +### Folders Tab + +The [Folders tab](/guardrails/docs/prevention/accounts/folders) groups accounts using Turbot Guardrails folders—logical groupings you define that can span multiple cloud providers. Folders might represent environments (dev, staging, prod), business units, or any other organizational structure that makes sense for your operations. + +Use this view when you need to analyze accounts by business context rather than cloud provider hierarchy, compare prevention coverage across logical groupings, or manage accounts that span multiple cloud providers. + +### Visualize Tab + +The [Visualize tab](/guardrails/docs/prevention/accounts/visualize) provides a graphical tree representation of your organization structure with prevention scores displayed visually. This view makes it easy to spot patterns—clusters of low-scoring accounts, organizational units with weak coverage, or inconsistencies in prevention implementation. + +Use this view when you want to see the big picture, identify patterns in prevention coverage, or communicate security posture to stakeholders through visual representation. + +## Understanding Account Prevention Scores + +[Account prevention scores](/guardrails/docs/prevention#prevention-scores) range from 0 to 5, indicating how well each account is protected: + +- **0-2**: Minimal coverage with significant gaps +- **3**: Moderate coverage with noticeable gaps +- **4**: Solid prevention implementation +- **5**: Comprehensive prevention across multiple layers + +Account scores aggregate all prevention objectives for that account, weighted by priority. A low score might indicate missing critical P1 controls or lack of coverage across many objectives. + +## Next Steps + +- Start with the [Accounts tab](/guardrails/docs/prevention/accounts/accounts) to find accounts needing attention +- Use the [Organizations view](/guardrails/docs/prevention/accounts/organizations) to understand cloud provider hierarchy +- Review the [Folders view](/guardrails/docs/prevention/accounts/folders) for business-context groupings +- Explore the [Visualize view](/guardrails/docs/prevention/accounts/visualize) for graphical patterns +- Review [Objectives](/guardrails/docs/prevention/objectives) to understand what's being measured diff --git a/docs/prevention/accounts/organizations/index.md b/docs/prevention/accounts/organizations/index.md new file mode 100644 index 00000000..71df5c25 --- /dev/null +++ b/docs/prevention/accounts/organizations/index.md @@ -0,0 +1,32 @@ +--- +title: Organizations +sidebar_label: Organizations +--- + +# Organizations + +The Organizations view displays cloud accounts organized by their native cloud provider hierarchy. This view shows the organizational structure as defined in AWS Organizations, Azure Management Groups, or GCP Organization hierarchy, making it easy to understand how accounts are structured and where prevention coverage may be inconsistent across organizational boundaries. + +![Organizations View](./organizations.png) + +## Understanding the Organizations View + +The Organizations view shows your cloud accounts in their native hierarchy—AWS Organizations with OUs and accounts, Azure Management Groups with subscriptions, or GCP Organization with folders and projects. Each level displays prevention scores, making it easy to see which branches of your organization have strong or weak coverage. + +This view is particularly useful for understanding prevention inheritance. Many preventions—especially Service Control Policies and Azure Policies—apply at the OU or management group level and affect all child accounts. Seeing the hierarchy helps you understand why certain accounts have specific preventions in place and where gaps might exist because a parent-level policy wasn't applied. + +If you see "No Organizational Units found," it means no cloud-native organizational structures have been imported yet. This view only appears when accounts belong to AWS Organizations, Azure Management Groups, or GCP Organization hierarchies. Standalone accounts without organizational context won't appear here—use the Accounts tab instead. + +## What Makes This Useful + +Expand organizational units to see which branches have lower prevention scores, helping you target remediation to specific business units or environments. If the Production OU scores 4.5 but the Development OU scores 2.0, you know where to focus effort—or you might decide that's acceptable risk tolerance for non-production environments. + +When different teams own different OUs, you can quickly compare their prevention maturity. If Team A's OU consistently scores higher than Team B's, that suggests Team A has better implemented preventive controls. This isn't about blame—it's about identifying where teams might need additional support, guidance, or resources to improve their security posture. + +The hierarchical view also clarifies why accounts have certain preventions. If an SCP is attached at the organization root, every account inherits it. If an Azure Policy applies at a management group, all subscriptions beneath it are affected. Understanding this inheritance helps you avoid accidentally removing protective controls or understand why an account can't perform certain actions. + +## Next Steps + +- Return to the [Accounts](/guardrails/docs/prevention/accounts) view for a flat list of all accounts +- Use the [Folders](/guardrails/docs/prevention/accounts/folders) view to see Turbot Guardrails logical groupings +- Click into any organizational unit or account to view detailed prevention scores diff --git a/docs/prevention/accounts/organizations/organizations.png b/docs/prevention/accounts/organizations/organizations.png new file mode 100644 index 00000000..c893a756 Binary files /dev/null and b/docs/prevention/accounts/organizations/organizations.png differ diff --git a/docs/prevention/accounts/visualize/index.md b/docs/prevention/accounts/visualize/index.md new file mode 100644 index 00000000..e94cd29e --- /dev/null +++ b/docs/prevention/accounts/visualize/index.md @@ -0,0 +1,68 @@ +--- +title: Visualize +sidebar_label: Visualize +--- + +# Visualize + +The Visualize page provides a graphical, interactive representation of your AWS Organization hierarchy and Service Control Policies (SCPs). This view helps you understand the structure of your AWS environment, see which accounts are grouped together, and visualize how SCPs are applied across organizational units. + +![Visualize](./visualize.png) + +## Understanding the Visualize View + +The Visualize view displays AWS Organizations as an interactive tree diagram showing your organization structure from top to bottom: the organization root, organizational units (OUs), and individual accounts. Lines connect the hierarchy to show relationships, and folded nodes (e.g., "3 Accounts") indicate collapsed groups that can be expanded. When the "Show SCPs" filter is enabled, visual indicators show where Service Control Policies are applied. + +This graphical representation makes it easy to see the entire organization structure at a glance, understand which accounts belong to which organizational units, and navigate complex multi-level organizational structures. + +## Interactive Features + +### Navigation + +- **Zoom In/Out**: Use the `+` and `−` buttons in the bottom-right corner, or use mouse wheel/touch gestures +- **Pan**: Click and drag on the background to move around the visualization +- **Fit View**: Click the `⊡` button to automatically fit the entire organization tree in the viewport +- **Reset Layout**: Click the `↻` button to reset the tree to its default layout +- **Node Selection**: Click on any organizational unit or account node to navigate to its detail page +- **Search**: Use the "Search graph..." box to quickly find and highlight specific OUs or accounts by name + +### Filtering + +![Visualize Filter Options](./visualize-filter.png) + +Use the **Filter** button to control what's displayed in the visualization: + +- **Show SCPs**: Toggle this switch to display or hide Service Control Policy attachments on the organization tree. When enabled, SCPs attached to the organization, root, OUs, or accounts will be visually indicated on the graph. +- **Show FullAWSAccess**: Toggle this switch to display or hide the FullAWSAccess SCP that AWS automatically attaches to every OU and account. Since these policies allow all actions and are present everywhere by default, hiding them can reduce visual clutter. + +The filter panel can be collapsed by clicking the Filter button again or by clicking outside the panel. + +### Exporting + +![Visualize Export Options](./visualize-export.png) + +Use the **Export** button to save the organization visualization in various formats: + +- **Export as PNG**: Download a high-quality image (1920x1080 resolution) of the entire organization tree, ideal for presentations and documentation +- **Export as SVG**: Download as scalable vector graphics, perfect for high-resolution printing or further editing in design tools +- **Export Viewport**: Export only the current visible viewport as PNG, useful for capturing a specific portion of the tree +- **Export as JSON**: Download the graph data structure (nodes and edges) in JSON format, useful for programmatic analysis or integration with other tools + + +## Common Use Cases + +- **When onboarding new team members or documenting architecture** - Use the visualization to quickly show how your AWS environment is organized. The graphical tree makes it easy to explain which accounts belong to which organizational units, how deep the hierarchy goes, and where specific accounts sit in the structure. Export as PNG or SVG for documentation. + +- **When analyzing SCP impact and inheritance** - Enable the "Show SCPs" filter to see which accounts are affected by Service Control Policies. Trace SCP inheritance from the organization root through OUs to individual accounts. This helps you understand the blast radius of policy changes and identify accounts that may be missing required preventions. + +- **When planning organizational restructuring** - Use the visualization to evaluate your current structure before making changes. See which accounts would be affected if you move them between OUs, identify OUs that might need consolidation or splitting, and understand dependencies before restructuring the organization hierarchy. + +- **When troubleshooting access or policy issues** - Search for a specific account experiencing issues, then trace upward through its OU hierarchy to see all inherited SCPs. This helps identify which policy at which level might be blocking an action or causing unexpected behavior. + + +## Next Steps + +- Return to the [Accounts](/guardrails/docs/prevention/accounts) view for a list of all accounts +- Use the [Organizations](/guardrails/docs/prevention/accounts/organizations) view for a table-based hierarchy view +- Use the [Folders](/guardrails/docs/prevention/accounts/folders) view to see Turbot Guardrails logical groupings +- Click into any account to view detailed prevention scores by objective diff --git a/docs/prevention/accounts/visualize/visualize-export.png b/docs/prevention/accounts/visualize/visualize-export.png new file mode 100644 index 00000000..523bddfd Binary files /dev/null and b/docs/prevention/accounts/visualize/visualize-export.png differ diff --git a/docs/prevention/accounts/visualize/visualize-filter.png b/docs/prevention/accounts/visualize/visualize-filter.png new file mode 100644 index 00000000..4fdd0c6d Binary files /dev/null and b/docs/prevention/accounts/visualize/visualize-filter.png differ diff --git a/docs/prevention/accounts/visualize/visualize.png b/docs/prevention/accounts/visualize/visualize.png new file mode 100644 index 00000000..4f9d3ca9 Binary files /dev/null and b/docs/prevention/accounts/visualize/visualize.png differ diff --git a/docs/prevention/dashboard/explore/index.md b/docs/prevention/dashboard/explore/index.md new file mode 100644 index 00000000..9e08b7b0 --- /dev/null +++ b/docs/prevention/dashboard/explore/index.md @@ -0,0 +1,71 @@ +--- +title: Explore +sidebar_label: Explore +--- + +# Explore + +The Explore tab lets you analyze prevention scores from multiple perspectives using custom grouping, filtering, and sorting. Think of it as a pivot table for your prevention data—you can arrange it by benchmark, account, category, layer, or priority, filter to specific subsets, and sort to find what matters most. + +![Prevention Explore](./prevention-explore-default.png) + +## Understanding the Explore View + +The view displays prevention data in a hierarchical table where [scores](/guardrails/docs/prevention#prevention-scores) aggregate at each level. By default, it groups by Benchmark > Objective > Account, but you can reorganize this however makes sense for your analysis. + +Each row shows the name and description, prevention score, and number of child items. Scores are calculated and displayed at every grouping level, rolling up from the most granular data to provide aggregate views at each hierarchy level. + +Click the expand/collapse arrow on any card to show or hide its children—this lets you drill down into details or collapse sections to see the big picture. Click on a card's title to navigate to its related detail page for comprehensive information about that specific item. + +## Grouping Data + +Organize your prevention data hierarchically using up to four levels from these options: + +- [Benchmark](/guardrails/docs/prevention/objectives/benchmarks) - Compliance frameworks +- [Objective](/guardrails/docs/prevention/objectives/objectives) - Prevention goals +- [Account](/guardrails/docs/prevention/accounts) - Cloud accounts +- [Category](/guardrails/docs/prevention/objectives/categories) - Security domains +- [Layer](/guardrails/docs/prevention/preventions/layers) - Enforcement stages +- [Priority](/guardrails/docs/prevention/objectives/priorities) - P1-P5 importance levels + +Drag and drop grouping handles in the Filter & Group panel to reorder levels. + +## Filtering and Sorting + +Filter to narrow data by layer, account, objective, category, or priority. This lets you focus on areas of responsibility or concern without noise from irrelevant data. + +Sort controls how items order within each group level: + +- Score (Asc) - Shows lowest scores first, useful for finding gaps needing attention +- Score (Desc) - Shows highest scores first, good for identifying your strongest areas +- Name (A-Z) - Provides alphabetical order for systematic reviews +- Priority (High to Low) - Puts critical objectives first for prioritization work + +## What to Look For + +Low scores indicate gaps in prevention coverage—opportunities to add SCPs, policies, or account settings to improve posture. Inconsistent scores across accounts (some score well, others don't) suggest inconsistent policy application—consider organization-wide policies. Missing layers (objectives covered at only one layer) signal opportunities for defense-in-depth by adding controls at additional layers. High-priority gaps (low scores on P1 or P2 objectives) represent the most critical risks and should be prioritized for remediation. + +## Common Use Cases + +**For compliance audit preparation**, group by Benchmark > Objective > Account, filter to the specific compliance framework, sort by Score (Asc) to identify failing objectives, then expand each low-scoring objective to see which accounts need remediation. + +![Compliance Audit Preparation](./prevention-explore-compliance-audit.png) + +**For account security reviews**, group by Account > Category > Objective, filter to the specific account, review scores across all categories, and identify objectives with low scores to understand what preventions exist (or don't). + +![Account Security Review](./prevention-explore-account-security-review.png) + +**For priority-driven remediation**, group by Priority > Category > Objective, filter to P1 and P2 priorities, sort by Score (Asc), and focus remediation on the lowest-scoring critical objectives first. + +![Priority-Driven Remediation](./prevention-explore-priority-remediation.png) + +**For layer coverage analysis**, group by Layer > Objective, review distribution of objectives across layers, identify objectives with coverage at only one layer, and plan additional controls at other layers for defense-in-depth. + +![Layer Coverage Analysis](./prevention-explore-layer-coverage.png) + +## Next Steps + +- Experiment with different grouping combinations to find views matching your analysis needs +- Use filters to focus on areas of concern or responsibility +- Bookmark useful views by copying the URL—filters and groupings are included in URL parameters +- Click through to individual objectives to see detailed prevention and recommendation information diff --git a/docs/prevention/dashboard/explore/prevention-explore-account-security-review.png b/docs/prevention/dashboard/explore/prevention-explore-account-security-review.png new file mode 100644 index 00000000..d972f72d Binary files /dev/null and b/docs/prevention/dashboard/explore/prevention-explore-account-security-review.png differ diff --git a/docs/prevention/dashboard/explore/prevention-explore-compliance-audit.png b/docs/prevention/dashboard/explore/prevention-explore-compliance-audit.png new file mode 100644 index 00000000..84c812c4 Binary files /dev/null and b/docs/prevention/dashboard/explore/prevention-explore-compliance-audit.png differ diff --git a/docs/prevention/dashboard/explore/prevention-explore-default.png b/docs/prevention/dashboard/explore/prevention-explore-default.png new file mode 100644 index 00000000..1ae04490 Binary files /dev/null and b/docs/prevention/dashboard/explore/prevention-explore-default.png differ diff --git a/docs/prevention/dashboard/explore/prevention-explore-layer-coverage.png b/docs/prevention/dashboard/explore/prevention-explore-layer-coverage.png new file mode 100644 index 00000000..77eeae21 Binary files /dev/null and b/docs/prevention/dashboard/explore/prevention-explore-layer-coverage.png differ diff --git a/docs/prevention/dashboard/explore/prevention-explore-priority-remediation.png b/docs/prevention/dashboard/explore/prevention-explore-priority-remediation.png new file mode 100644 index 00000000..36a5eb19 Binary files /dev/null and b/docs/prevention/dashboard/explore/prevention-explore-priority-remediation.png differ diff --git a/docs/prevention/dashboard/index.md b/docs/prevention/dashboard/index.md new file mode 100644 index 00000000..713589e0 --- /dev/null +++ b/docs/prevention/dashboard/index.md @@ -0,0 +1,41 @@ +--- +title: Dashboard +sidebar_label: Dashboard +--- + +# Dashboard + +The Prevention Dashboard gives you a single-page view of your preventive security posture—your overall prevention score, how you're tracking against compliance benchmarks, top recommendations for improvement, and breakdowns by category and layer. This is your starting point for understanding where you stand and where to focus effort. + +![Prevention Dashboard](./prevention-dashboard-overview.png) + +## Overall Maturity + +Your [prevention score](/guardrails/docs/prevention#prevention-scores) (0-5 scale) appears at the top, reflecting how effectively your preventions meet security objectives across all accounts. The score considers coverage (how many objectives have preventions), quality (how strong those preventions are through layer weighting), and importance (priority weighting). Below the score you'll see total objectives being tracked and total preventions discovered in your environment. Click this section to explore detailed scores by account and objective. + +## Benchmarks + +Shows your prevention scores against compliance frameworks—AWS CIS, NIST 800-53, Azure CIS, GitHub CIS, and P1 Preventions for each platform. Each benchmark card displays the name, description, and your current score. This helps you quickly see how close you are to compliance certification or where gaps exist. Click View All to see your complete list of benchmarks and drill into objective-level details. + +## Recommendations + +Your top 3 recommendations for improving prevention posture appear here. Each shows the objective title, priority level (P1-P5), what will be accomplished when implemented, and concrete implementation guidance. These are prioritized by opportunity—considering security impact, coverage gaps, and compliance requirements—so the highest-value work surfaces first. Click View All to browse all available recommendations and their detailed implementation steps. + +## Categories + +Shows your prevention score for each of the seven security domains—Identity & Access (privileged access and authentication), Feature Restrictions (disabling risky service features), Trust & Sharing (external access prevention), Data Governance (data protection and encryption), Network Perimeter (connectivity restrictions), Core Infrastructure (foundational governance protections), and Audit & Logging (audit trail protection). + +Each category card shows the number of objectives and your prevention score. This helps spot imbalances—if most categories score 4+ but Data Governance scores 1.5, you know where to focus. Click any category or View All to explore objectives and detailed scores. + +## Layers + +Shows how your preventions are distributed across enforcement layers—Build (IaC scanning and CI/CD controls), Access (organization-level policies like SCPs and Azure Policies), Config (account and service settings enforcing secure defaults), and Runtime (real-time remediation and enforcement). + +Each layer card shows the number of objectives with controls at that layer and your prevention score. Balanced coverage across layers provides defense-in-depth—if one layer fails, others provide backup. Click any layer or View All to analyze your defense-in-depth strategy. + +## Next Steps + +- Click any section on the dashboard to drill into detailed scores and analysis +- Use the [Explore](/guardrails/docs/prevention/dashboard/explore) tab to customize groupings and filters for deeper investigation +- Review [Reports](/guardrails/docs/prevention/dashboard/reports) for specialized views like service boundaries and region restrictions +- Implement your top recommendations—starting with P1 priorities—and monitor your score over time as you add new preventions and expand coverage diff --git a/docs/prevention/dashboard/prevention-dashboard-overview.png b/docs/prevention/dashboard/prevention-dashboard-overview.png new file mode 100644 index 00000000..8b377600 Binary files /dev/null and b/docs/prevention/dashboard/prevention-dashboard-overview.png differ diff --git a/docs/prevention/dashboard/reports/index.md b/docs/prevention/dashboard/reports/index.md new file mode 100644 index 00000000..38f2591f --- /dev/null +++ b/docs/prevention/dashboard/reports/index.md @@ -0,0 +1,53 @@ +--- +title: Reports +sidebar_label: Reports +--- + +# Reports + +The Reports tab shows the effective security boundaries in your cloud environment—answers to practical questions like "Which AWS services can my developers use?" or "What regions are blocked across my organization?" These reports aggregate prevention data to show net effects rather than individual policies, making them particularly valuable for troubleshooting (understanding why operations are blocked), compliance auditing (verifying boundaries match policies), change validation (confirming preventions work as intended), and communication (explaining boundaries to development teams). + +![Prevention Reports](./prevention-reports-overview.png) + +## Available Reports + +### AWS Region Boundary + +Shows which AWS regions are allowed or denied for each account in a matrix table. This aggregates all preventions (SCPs, RCPs, access policies) to show actual usable regions—helpful for identifying which regions are available in each account, spotting inconsistencies in region policies across accounts, verifying compliance with data residency requirements, and understanding effective region boundaries. + +![AWS Region Boundary Report](./prevention-report-aws-region-boundary.png) + +### AWS Service Boundary + +Shows which AWS services are allowed or denied for each account in a matrix table. This aggregates all preventions to show which services are available after all policies are evaluated—useful for seeing which AWS services can be provisioned in each account, identifying service restrictions that may block legitimate workloads, verifying high-risk services are properly restricted, and understanding your allowed service catalog. + +![AWS Service Boundary Report](./prevention-report-aws-service-boundary.png) + +### Guardrails AWS Region Boundary Exceptions + +Identifies regions allowed by preventions (SCPs, RCPs) but NOT listed in the `Guardrails AWS > Account > Approved Regions` policy. These exceptions may indicate policy drift (SCPs and Guardrails policies are out of sync), security concerns (regions allowed at SCP level but not approved in Guardrails), or configuration errors (Guardrails policy needs updating). This is useful when using both preventions and Guardrails runtime controls to maintain consistency between access-layer and runtime-layer enforcement. + +![Guardrails AWS Region Boundary Exceptions Report](./prevention-report-guardrails-aws-region-boundary-exceptions.png) + +## How Reports Work + +Reports are derived from prevention facts—information extracted from your preventions. When Guardrails discovers an SCP deny statement blocking EC2 in us-west-1, it creates a fact recording that region as blocked. Reports aggregate these facts across accounts to show the complete picture. + +Service and region boundaries are calculated by evaluating deny statements in SCPs and RCPs that block services or regions, allow boundaries defined by SCP allow statements (when using allow lists), service control settings like enabled/disabled services, and inheritance of policies from parent organizational units. Reports show the effective boundary—what is actually accessible after all policies are applied. + +## Common Use Cases + +- **When onboarding new accounts** - Review service and region boundary reports to understand what will be available based on organizational SCPs. This helps set expectations with teams about which services and regions they can use before they start deploying workloads. + +- **When troubleshooting deployment failures** - Check the service boundary report if deployments fail with access denied errors. The report shows which services are actually blocked, helping you identify if an SCP is causing the issue and which account or OU needs an exception. + +- **For compliance reporting** - Use region boundary reports to demonstrate resources cannot be created in non-compliant regions. These reports provide clear evidence that your preventions enforce data residency requirements, which auditors often request. + +- **After implementing new preventions** - Review boundary reports to validate they produce intended effects. If you just deployed an SCP to block a specific service, check the service boundary report to confirm the service now shows as denied for the expected accounts. + +## Next Steps + +- Review the AWS Service Boundary report to verify your allowed services +- Check the AWS Region Boundary report to ensure data residency requirements are enforced +- If using Guardrails runtime controls, review Region Boundary Exceptions to identify policy drift +- Use reports during security reviews and compliance audits diff --git a/docs/prevention/dashboard/reports/prevention-report-aws-region-boundary.png b/docs/prevention/dashboard/reports/prevention-report-aws-region-boundary.png new file mode 100644 index 00000000..3eac9839 Binary files /dev/null and b/docs/prevention/dashboard/reports/prevention-report-aws-region-boundary.png differ diff --git a/docs/prevention/dashboard/reports/prevention-report-aws-service-boundary.png b/docs/prevention/dashboard/reports/prevention-report-aws-service-boundary.png new file mode 100644 index 00000000..deba2107 Binary files /dev/null and b/docs/prevention/dashboard/reports/prevention-report-aws-service-boundary.png differ diff --git a/docs/prevention/dashboard/reports/prevention-report-guardrails-aws-region-boundary-exceptions.png b/docs/prevention/dashboard/reports/prevention-report-guardrails-aws-region-boundary-exceptions.png new file mode 100644 index 00000000..55983952 Binary files /dev/null and b/docs/prevention/dashboard/reports/prevention-report-guardrails-aws-region-boundary-exceptions.png differ diff --git a/docs/prevention/dashboard/reports/prevention-reports-overview.png b/docs/prevention/dashboard/reports/prevention-reports-overview.png new file mode 100644 index 00000000..303a698e Binary files /dev/null and b/docs/prevention/dashboard/reports/prevention-reports-overview.png differ diff --git a/docs/prevention/index.md b/docs/prevention/index.md new file mode 100644 index 00000000..c219ed67 --- /dev/null +++ b/docs/prevention/index.md @@ -0,0 +1,133 @@ +--- +title: Prevention +--- + +# Prevention + +
+ + +
+ +Turbot Guardrails enables prevention-first cloud security, stopping misconfigurations, policy violations, and risky deployments before they reach production. + +## Understanding Prevention-First Security + +Most security tools tell you what's wrong after something's already deployed—a public S3 bucket, an unencrypted database, a security group open to the world. Prevention-first security stops these issues before they reach production. Guardrails discovers the preventions already in your environment (Service Control Policies, Azure Policies, account settings, etc.), maps them to security objectives, and scores how well you're preventing issues before they can occur. + +## Key Concepts + +### Objectives + +[Objectives](/guardrails/docs/prevention/objectives) are security goals—the outcomes you're trying to achieve. "Restrict AWS resources to allowed regions" is an objective. "Require encryption at rest for AWS EBS volumes" is another. "Prohibit public access to S3 buckets" is a third. These aren't preventive mechanisms; they're the security requirements you need to meet. + +Each objective has a category (like Data Governance or Identity & Access) that groups related goals, and a priority (P1 through P5) indicating how critical it is. P1 objectives are foundational preventions that should be implemented everywhere. P4-P5 objectives are nice-to-haves. + +### Preventions + +[Preventions](/guardrails/docs/prevention/preventions) are the actual preventive mechanisms implementing your objectives. While objectives describe what you're trying to accomplish, preventions are how you're accomplishing it. To achieve "require encryption at rest for AWS EBS volumes," you might have an SCP denying unencrypted volume creation, an EC2 account setting enabling default encryption, and a Guardrails control remediating any unencrypted volumes. All three preventions contribute to the same objective. + +Each prevention has a [type](/guardrails/docs/prevention/preventions/types) (Service Control Policy, Azure Policy, account setting, etc.) that determines how it works and a layer (Build, Access, Config, or Runtime) that indicates when it operates in the resource lifecycle. + +### Layers + +Preventions operate at different points in time, which we call [layers](/guardrails/docs/prevention/preventions/layers). Build layer preventions catch problems in Infrastructure as Code before deployment. Access layer preventions block dangerous API calls at the organization level. Config layer preventions enforce settings on existing resources. Runtime layer preventions detect and respond to issues during operation. + +The layer affects both timing and defensive strength. Access layer preventions (weighted 0.95) score highest because they're hardest to bypass and apply most broadly. Build layer preventions (weighted 0.75) score slightly lower because they only apply to IaC-managed resources. Defense-in-depth means having preventions at multiple layers—if one fails, others provide backup. + +### Categories + +[Categories](/guardrails/docs/prevention/objectives/categories) organize objectives by security domain—Identity & Access, Data Governance, Trust & Sharing, Network Perimeter, Core Infrastructure, Audit & Logging, and Feature Restrictions. This organization helps ensure balanced security coverage. You might have excellent identity preventions but weak data protection, or strong network defenses but poor audit logging. The category view makes these imbalances visible. + +### Priorities + +[Priorities](/guardrails/docs/prevention/objectives/priorities) indicate how critical each objective is. P1 objectives are foundational preventions that should be implemented immediately—things like restricting resources to allowed regions, requiring MFA for root accounts, and blocking public databases. P2 objectives provide strong security improvements. P3 objectives enhance posture through defense-in-depth. P4-P5 objectives are optimizations and hygiene. + +Priority weighting uses a reverse Fibonacci sequence: P1 objectives have 8x the weight of P5 objectives. This means improving a single P1 objective has more impact on your score than improving multiple lower-priority objectives—reflecting the reality that fixing critical gaps matters more than polishing edge cases. + +### Benchmarks + +[Benchmarks](/guardrails/docs/prevention/objectives/benchmarks) are compliance frameworks that organize objectives—AWS CIS v6.0.0, NIST 800-53 Rev 5, Azure CIS v5.0.0, and so on. Each benchmark shows your prevention score for that framework, helping you track progress toward compliance certification. Many objectives appear in multiple benchmarks, so implementing one prevention can improve multiple framework scores simultaneously. + +### Recommendations + +[Recommendations](/guardrails/docs/prevention/objectives/recommendations) are prioritized suggestions for what to implement next. They target specific objectives where you have coverage gaps, explain the security impact, and provide implementation guidance. Recommendations are ordered by potential risk reduction, considering both the objective's priority and your current coverage level. + +## Prevention Scores + +Prevention scores measure how well you're preventing security issues before they occur. Understanding how scores are calculated helps you interpret what they mean and where to focus improvement efforts. + +#### The Scale + +Prevention scores range from 0 to 5: + +- **0-1**: Minimal or no preventions—significant security gaps exist +- **2**: Limited prevention coverage—some preventions in place but major gaps remain +- **3**: Moderate coverage with noticeable gaps—basic protections exist but not comprehensive +- **4**: Solid prevention implementation—good coverage across most areas +- **5**: Comprehensive prevention across multiple layers—strong defense-in-depth + +Scores aren't pass/fail thresholds—they're maturity indicators showing where you are and how much work remains. Going from 2.0 to 3.5 represents meaningful progress even if you haven't reached 5.0. + +#### What Goes Into a Score + +Three factors determine prevention scores: + +**Coverage** - Which objectives have preventions in place. An objective with no preventions scores 0. An objective with preventions in some accounts but not others scores in the middle range. An objective with preventions across all applicable accounts scores higher. + +**Layer Weighting** - How strong those preventions are based on when they operate. Preventions at different layers have different defensive strength: +- **Access layer** (0.95 weight) - Control who can do what (API-level authorization) +- **Config layer** (0.85 weight) - Enforce secure defaults everywhere +- **Runtime layer** (0.75 weight) - Auto-fix in real time +- **Build layer** (0.55 weight) - Catch problems before launch (lowest weight - less runtime guarantee) + +An objective protected by an Access layer SCP scores higher than the same objective protected only by a Runtime remediation control. + +**Priority Weighting** - How important the objective is. Priorities indicate the severity of security objectives: +- **P1** (weight 8) - Direct path to data breach or service compromise +- **P2** (weight 5) - Significant security or compliance risk +- **P3** (weight 3) - Best practice violations with moderate risk +- **P4** (weight 2) - Optimization and hygiene issues +- **P5** (weight 1) - Low-priority items + +This means P1 objectives have 8x the weight of P5 objectives. At the account level, priority weighting is applied as: `account_score = 100 × Σ(coverage × priority_weight) / Σ(priority_weight)`. This gives higher-priority objectives more influence on the overall account score, reflecting the reality that fixing critical gaps matters more than polishing edge cases. + +#### Score Aggregation + +Scores aggregate at every level of your environment using a three-level calculation pattern: + +**1. Atomic Level** - Individual rule evaluation where `effective_coverage = quality × layer_weight`. This is where layer weight is applied, and it's never re-applied in higher rollups. + +**2. Within-Account (same objective, multiple rules)** - Uses probabilistic OR to model defense-in-depth redundancy: `combined = 1 - Π(1 - effective_coverage_i)`. When multiple preventions protect the same objective in the same account, they provide redundant layers of defense. + +**3. Cross-Account (same objective, multiple accounts)** - Uses simple average: `score = Σ(coverage) / count(accounts)`. Accounts are independent security boundaries, not redundant defenses, so their scores are averaged. + +These calculations produce the following aggregated views: + +**Objective scores** - How well a specific objective (like "prohibit public S3 buckets") is met across all applicable accounts. Considers coverage, layer weighting, and the preventions in place. + +**Account scores** - How well a specific account is protected across all objectives. Aggregates all objective scores for that account, weighted by priority. + +**Category scores** - How well a security domain (like Data Governance or Identity & Access) is covered. Aggregates objective scores within that category, weighted by priority. + +**Benchmark scores** - How well you meet a compliance framework (like AWS CIS or NIST 800-53). Aggregates scores for all objectives in that benchmark, weighted by priority. + +**Overall score** - Your total prevention posture across all objectives and accounts, weighted by priority. + +This aggregation lets you analyze security from multiple perspectives—by account, by objective, by category, by compliance framework—and identify exactly where to focus improvement efforts. + +#### Context Matters + +Don't interpret scores in isolation: + +**Trends matter more than snapshots** - If your score is improving over time, you're making progress. A score stuck at 2.5 for six months indicates stagnation. + +**Priority creates urgency** - A P1 objective scoring 2 is urgent—it's a critical prevention with major gaps. A P4 objective scoring 2 is lower priority—it's nice to fix but not critical. + +**Balance matters** - A balanced security program typically has reasonably consistent scores across categories (maybe 3.5-4.5 across the board). Highly unbalanced programs (5.0 for Identity & Access but 1.5 for Data Governance) indicate resource allocation problems. + +**Perfect scores aren't always the goal** - Some organizations set practical targets: "All P1 objectives must score 4+ in production accounts. P2 objectives should score 3+. P3-P5 are discretionary." This creates clear expectations and measurable goals without demanding perfection everywhere. diff --git a/docs/prevention/objectives/benchmarks/benchmark-detail-expanded.png b/docs/prevention/objectives/benchmarks/benchmark-detail-expanded.png new file mode 100644 index 00000000..749075ed Binary files /dev/null and b/docs/prevention/objectives/benchmarks/benchmark-detail-expanded.png differ diff --git a/docs/prevention/objectives/benchmarks/benchmark-detail.png b/docs/prevention/objectives/benchmarks/benchmark-detail.png new file mode 100644 index 00000000..d8c9dbdb Binary files /dev/null and b/docs/prevention/objectives/benchmarks/benchmark-detail.png differ diff --git a/docs/prevention/objectives/benchmarks/benchmarks-list.png b/docs/prevention/objectives/benchmarks/benchmarks-list.png new file mode 100644 index 00000000..6574185b Binary files /dev/null and b/docs/prevention/objectives/benchmarks/benchmarks-list.png differ diff --git a/docs/prevention/objectives/benchmarks/index.md b/docs/prevention/objectives/benchmarks/index.md new file mode 100644 index 00000000..45d4ec12 --- /dev/null +++ b/docs/prevention/objectives/benchmarks/index.md @@ -0,0 +1,83 @@ +--- +title: Benchmarks +sidebar_label: Benchmarks +--- + +# Benchmarks + +Benchmarks are compliance frameworks that define what good security looks like for a specific cloud provider or technology. When you need to prove compliance with AWS CIS, meet NIST 800-53 requirements, or follow Azure security best practices, this is where you track your progress. + +![Benchmarks View](./benchmarks-list.png) + +## What You're Looking At + +Each card represents a compliance framework. AWS CIS v6.0.0 is the Center for Internet Security's benchmark for AWS—a collection of security objectives that, when implemented, represent industry best practice. NIST 800-53 Rev 5 is the federal government's security control framework. The "P1 Preventions" benchmarks are Turbot's own frameworks focusing on the most critical preventive controls for each cloud provider. + +The score next to each benchmark tells you how well you're meeting that framework's requirements across all your accounts. A score of 5 means you're fully compliant—every objective in the benchmark is being met. A score of 2 means you're missing most of the requirements. This isn't a pass/fail—it's a maturity indicator showing where you are and how much work remains. + +What makes this view valuable is seeing all your frameworks in one place. Instead of tracking AWS CIS compliance separately from NIST 800-53 compliance, you can see both scores immediately and prioritize based on which certifications matter most to your organization. + +## How Benchmarks Are Organized + +Benchmarks aren't flat lists—they're hierarchical. Click into AWS CIS v6.0.0 and you'll see it's organized into sections like "Identity and Access Management," "Storage," and "Logging." Each section contains related objectives. For example, the IAM section might include "Require MFA for root user" and "Eliminate use of root user for administrative and daily tasks." + +This structure mirrors how the frameworks themselves are published, making it easier to map audit requirements to your implementation. When an auditor asks about CIS section 1.5, you can navigate directly to that section and see your current state. + +## Common Use Cases + +- **When pursuing compliance certification** - Click into your target benchmark (like AWS CIS) and review the sections. Sections with low scores need attention—click through to see which specific objectives aren't being met. From there, you can identify what preventions you need to implement. + +- **When managing multiple frameworks** - Sort by score to see which benchmarks need the most work. Search for "CIS" to see all your CIS frameworks across different cloud providers at once. This helps you prioritize where to focus compliance efforts. + +- **For establishing security baselines** - Start with the P1 Preventions benchmarks as your baseline. These represent Turbot's view of the most critical controls for each cloud. Once you have strong P1 coverage, layer on compliance frameworks like CIS or NIST as needed for certification. + +## Working With Benchmark Scores + +[Benchmark scores](/guardrails/docs/prevention#prevention-scores) measure compliance framework coverage on a 0-5 scale. Don't fixate on achieving perfect 5.0 scores immediately—compliance is a journey. Going from 2.0 to 3.5 represents months of work and meaningful progress. Focus on section-level scores to identify weak areas. If your overall CIS score is 3.2 but the Logging section scores 1.5, you know where to focus. + +Some benchmarks overlap significantly. Many controls that satisfy AWS CIS also satisfy NIST 800-53. This means implementing one prevention can improve multiple benchmark scores simultaneously. The system tracks this automatically, so you don't need to manually map controls to frameworks. + +A practical approach: start with P1 Preventions to build your foundation, then pursue compliance frameworks as business needs dictate. If you're selling to government customers, prioritize NIST 800-53. If you're in healthcare, prioritize frameworks that align with HIPAA requirements. Focus on one benchmark at a time rather than spreading effort across multiple frameworks—complete one, then move to the next. + +## Benchmark Detail View + +Clicking any benchmark opens the Benchmark Detail page, which provides a comprehensive view of that compliance framework, showing how your organization scores against each section of the benchmark and which specific objectives need attention. + +![Benchmark Detail Page showing sections and scores](./benchmark-detail.png) + +The Benchmark Detail page shows: + +**Hierarchical Sections** - Benchmarks organize into collapsible sections representing logical groupings. AWS CIS v6.0.0, for example, has sections like Identity and Access Management (21 items), Storage (3 items), Logging (9 items), Monitoring (16 items), and Networking (7 items). Each section shows its description, item count, and prevention score (0-5). + +**Section Scores** - Show compliance within each grouping. High-scoring sections indicate strong coverage in that domain while low-scoring sections highlight areas needing attention. Section scores matter because some compliance frameworks require minimum scores in specific sections. + +**Individual Objectives** - Click any section to expand and view individual objectives with their titles, descriptions, priority levels (P1-P4), current scores, and categories. This hierarchical view helps you identify which sections have lower scores and focus remediation on specific benchmark areas. + +### Using the Detail View + +![Benchmark Detail with expanded sections showing objectives](./benchmark-detail-expanded.png) + +The benchmark detail view is interactive—click any section header to expand or collapse it. Collapsed sections show just the section name, item count, and score. Expanded sections reveal the individual objectives within that section, each with its own score, priority level, and description. + +Each section displays its score (0-5) on the right side. These section scores help you quickly identify which areas of the benchmark need the most attention. For example, if "Storage" scores 4 but "Identity and Access Management" scores 2, you know IAM controls need work. + +When you expand a section, you'll see subsections (if the benchmark has nested structure) or individual objectives. Each objective card shows: +- The objective title and description +- Priority level (P1-P4) indicating criticality +- Category badge (Data Governance, Identity & Access, etc.) +- Current score (0-5) showing how well you're meeting this objective + +Click any objective to open its detail page, where you can see which accounts meet the objective, what preventions achieve it, and implementation recommendations. + +**To assess compliance against a benchmark**: Review the overall score in the header, scan section scores to identify weak areas, expand low-scoring sections to see specific objectives, and note which objectives score below your target threshold. + +**When planning remediation work**: Identify sections with the lowest scores, expand those sections to see individual objectives, click on each objective to understand why it's important and what preventions are needed, create a remediation plan prioritizing P1 and P2 objectives, and track progress by monitoring section scores over time. + +**For comparing compliance across frameworks**: Open multiple benchmark detail pages, compare overall scores, identify common objectives that appear in multiple benchmarks, and focus on implementing objectives that satisfy multiple frameworks. + +## Next Steps + +- Review [Objectives](/guardrails/docs/prevention/objectives/objectives) to see all individual objectives across all benchmarks +- Check [Priorities](/guardrails/docs/prevention/objectives/priorities) to focus on critical objectives first +- View [Categories](/guardrails/docs/prevention/objectives/categories) to ensure balanced security coverage +- Visit [Recommendations](/guardrails/docs/prevention/objectives/recommendations) for implementation guidance diff --git a/docs/prevention/objectives/categories/categories-view.png b/docs/prevention/objectives/categories/categories-view.png new file mode 100644 index 00000000..b9ae3ecd Binary files /dev/null and b/docs/prevention/objectives/categories/categories-view.png differ diff --git a/docs/prevention/objectives/categories/index.md b/docs/prevention/objectives/categories/index.md new file mode 100644 index 00000000..62c91b5d --- /dev/null +++ b/docs/prevention/objectives/categories/index.md @@ -0,0 +1,81 @@ +--- +title: Categories +sidebar_label: Categories +--- + +# Categories + +Categories organize objectives by security domain—Identity & Access, Data Governance, Trust & Sharing, and so on. This view helps you spot blind spots. You might have excellent identity preventions but weak data protection, or strong network perimeter defenses but poor audit logging. Balanced coverage across categories generally means stronger overall security. + +![Categories view showing objectives grouped by security domain](./categories-view.png) + +## Why Categories Matter + +Security isn't just one thing—it's protecting data, managing identities, controlling network access, maintaining audit trails, and more. Focusing too heavily on one category while neglecting others creates vulnerabilities. Attackers don't need to break through your strongest defenses; they'll exploit your weakest area. + +The category view makes these imbalances visible. If your Identity & Access objectives score 4.5 on average but your Data Governance objectives score 2.1, you have a problem. You might prevent unauthorized access perfectly, but once someone gets in (insider threat, compromised credential), your data isn't protected. + +## The Seven Security Domains + +### Core Infrastructure + +Core Infrastructure objectives protect the foundational preventions and governance capabilities that make everything else work. This includes restricting resources to allowed regions (so you can actually monitor and protect them), limiting which cloud services can be used (reducing attack surface), and protecting the infrastructure that provides governance—like AWS Config, IAM Access Analyzer, or Azure landing zones. + +If you don't restrict resources to allowed regions, you might have workloads running in regions where your security tools don't operate. If you don't enforce IMDSv2 on EC2 instances, metadata service exploits remain possible. + +Common gaps include allowing resources in too many regions, not restricting risky or unnecessary services, and not protecting the governance infrastructure itself from deletion or modification. + +### Data Governance + +Data Governance covers everything related to protecting the data itself—encryption at rest, encryption in transit, public access controls, data classification, lifecycle management, and secret scanning. This category often has the most objectives because data protection touches so many services and configurations. + +Common gaps include unencrypted data stores, missing soft delete capabilities, lack of data classification tags, and no secret scanning in source code repositories. Many organizations implement strong perimeter and identity preventions but leave data itself poorly protected. + +### Identity & Access + +Identity & Access objectives restrict privileged access—root account usage, administrative permissions, MFA requirements, credential management. These preventions prevent account takeover, privilege escalation, and unauthorized access to sensitive capabilities. + +Common gaps include root access keys still existing, no MFA on root accounts, overly permissive IAM policies granting wildcard permissions, and too many users with administrative access. These gaps are often remnants of early-stage fast development that were never cleaned up. + +### Trust & Sharing + +Trust & Sharing objectives prevent external or anonymous access. This includes blocking public S3 buckets, preventing public databases, restricting cross-account access, and controlling external sharing of resources. The category is about defining and enforcing trust boundaries—who should have access and who shouldn't. + +Common gaps include permitting public resource creation, not controlling cross-account IAM trust relationships, allowing anonymous access to cloud resources, and permitting overly broad resource sharing via service-specific mechanisms. + +### Network Perimeter + +Network Perimeter objectives restrict network connectivity—VPC configurations, security group rules, network ACLs, and traffic patterns. These preventions control how network traffic flows between resources, from internet to cloud, and between cloud environments. + +Common gaps are allowing unrestricted inbound SSH or RDP (opening every instance to brute force attacks), not using private endpoints for sensitive services, overly permissive security groups, and lack of network segmentation between environments. + +### Audit & Logging + +Audit & Logging objectives protect audit trails and logging infrastructure. This includes enabling CloudTrail, protecting log data from deletion or modification, ensuring diagnostic settings are configured, and maintaining log retention. These preventions support forensics, compliance, and incident response. + +Without logs, you can't investigate incidents, prove compliance, or detect attacks. An attacker's first move after compromise is often to disable logging or delete logs to hide their activity. + +Common gaps include not enabling CloudTrail in all regions, not protecting CloudTrail from deletion or modification, missing log retention policies, not enabling diagnostic settings on key resources, and not protecting log storage from deletion. + +### Feature Restrictions + +Feature Restrictions objectives disable or limit risky service features—things like disabling EC2 serial console access, restricting Lambda function URLs, or controlling which AMIs can be launched. + +These preventions reduce attack surface by removing capabilities that aren't needed. If you don't use Lambda function URLs, disabling them eliminates that attack vector. If you only use specific AMIs, restricting others prevents launching untrusted images. + +Common gaps are leaving unused service features enabled, not restricting which resources or configurations are permitted, and allowing risky features without compensating preventions. + +## Common Use Cases + +- **To identify security blind spots** - Review the average [score](/guardrails/docs/prevention#prevention-scores) for each category. If most categories score 3.5-4.5 but one scores 1.5-2.5, that's your weak domain. Even if you have excellent overall coverage, the weak category represents a vulnerability attackers can exploit. + +- **To assess balanced coverage** - A balanced security program typically has reasonably consistent scores across categories—maybe 3.5-4.5 across the board. Highly unbalanced programs—like 5.0 for Identity & Access but 1.5 for Data Governance—indicate resource allocation problems or strategic gaps. + +- **Understanding environment-specific imbalances** - Some imbalance is normal based on your environment. If you're primarily using serverless architectures, Network Perimeter might be less relevant than Data Governance. If you're heavily IaC-driven, Core Infrastructure (region restrictions, service restrictions) might score higher naturally. + +## Next Steps + +- Click into any category to see all its objectives and current scores +- Review [Priorities](/guardrails/docs/prevention/objectives/priorities) to ensure high-priority objectives are addressed across all categories +- Check [Benchmarks](/guardrails/docs/prevention/objectives/benchmarks) to see how categories map to compliance frameworks +- Visit [Recommendations](/guardrails/docs/prevention/objectives/recommendations) to get guidance on improving weak categories diff --git a/docs/prevention/objectives/index.md b/docs/prevention/objectives/index.md new file mode 100644 index 00000000..d0860952 --- /dev/null +++ b/docs/prevention/objectives/index.md @@ -0,0 +1,53 @@ +--- +title: Objectives +sidebar_label: Objectives +--- + +# Objectives + +The Objectives page shows what you're trying to accomplish with your preventions. While the Preventions page shows the preventive mechanisms you've implemented, the Objectives page focuses on the security goals those preventions achieve—things like "require encryption at rest" or "prohibit public access to databases." + +## What Objectives Represent + +Think of objectives as your security requirements. Each objective describes a specific outcome you want to enforce across your cloud environment. "Prohibit public access to AWS RDS DB instances" is an objective. "Require MFA for AWS root user authentication" is another. These aren't technical implementations—they're the goals. + +The value of organizing by objectives is that it lets you see whether your goals are being met, regardless of how they're technically implemented. You might achieve "restrict AWS resources to allowed regions" through an SCP, a Guardrails control, and an Azure Policy. The objective view rolls all of those up and tells you: yes, this goal is being met, and here's your score across all accounts. + +Objectives are organized by priority (P1 for critical down to P4 for lower priority), category (like Identity & Access or Data Governance), and benchmark (like CIS or NIST). This organization helps you focus on what matters most and ensures you're covering all the security domains that matter to your organization. + +## Different Ways to View Objectives + +The Objectives section provides five different perspectives, each useful for different situations. + +The **[Benchmarks tab](/guardrails/docs/prevention/objectives/benchmarks)** organizes objectives according to compliance frameworks like AWS CIS v6.0.0, NIST 800-53, or Azure CIS v5.0.0. This view is essential when you're pursuing compliance certification or need to report against a specific standard. Each benchmark shows your current score, and clicking into it reveals which sections need attention. + +The **[Objectives tab](/guardrails/docs/prevention/objectives/objectives)** lists every objective individually with its current score and priority. This is useful when you're looking for a specific objective or want to see everything at once. You can search for "encryption" or "MFA" and immediately see all related objectives and how well you're meeting them. + +The **[Recommendations tab](/guardrails/docs/prevention/objectives/recommendations)** flips the view to show what you should do next. Instead of browsing objectives yourself, it presents prioritized actions based on your coverage gaps, focusing on high-impact improvements. + +The **[Priorities tab](/guardrails/docs/prevention/objectives/priorities)** groups objectives by their risk level—P1 objectives are fundamental preventions that should be implemented everywhere, while P4 objectives are nice-to-haves. This view helps you focus on what matters most first. + +The **[Categories tab](/guardrails/docs/prevention/objectives/categories)** organizes by security domain—Identity & Access, Data Governance, Trust & Sharing, and so on. This ensures you're not over-invested in one area while neglecting another. Balanced coverage across categories generally means stronger overall security. + +## How to Use This Information + +When you're working toward compliance certification, start with the Benchmarks tab. Find your target framework (like AWS CIS v6.0.0), check your current score, and drill into the lowest-scoring sections. Each section shows which objectives you're not meeting, and from there you can click through to see what preventions would help. + +If you're prioritizing security work without a specific compliance target, the Priorities tab is more useful. Start with P1 objectives that have low scores—these are fundamental preventions that should be in place everywhere. Once P1 coverage is solid, move to P2, and so on. + +The Categories tab helps prevent blind spots. You might have excellent Identity & Access coverage but weak Data Governance. The category view makes these imbalances visible so you can address them before they become problems. + +For day-to-day work, the Objectives tab with search is fastest. If someone asks "do we enforce MFA?" you can search for "MFA," see the relevant objectives, check the scores, and answer immediately. + +## Understanding Objective Scores + +[Objective scores](/guardrails/docs/prevention#prevention-scores) range from 0 to 5, measuring how well a specific security goal is met across all your accounts. A score of 5 means the objective is fully met everywhere with strong preventions. A score of 0-1 means you're not meeting the objective—preventions are missing, weak, or narrowly scoped. + +The score considers coverage (how many accounts have preventions), layer weighting (Access layer preventions score higher than Runtime), and priority (a low score on a P1 objective is more urgent than on a P4 objective). Trends matter—if your score is improving, you're making progress. + +## Next Steps + +- Click into any [benchmark](/guardrails/docs/prevention/objectives/benchmarks#benchmark-detail-view) to see its grouped objectives +- Click into any [objective](/guardrails/docs/prevention/objectives/objectives#objective-detail-view) to see which accounts meet it and which preventions achieve it +- Review [Recommendations](/guardrails/docs/prevention/objectives/recommendations) for prioritized implementation guidance +- Return to [Accounts](/guardrails/docs/prevention/accounts) to see prevention scores by account diff --git a/docs/prevention/objectives/objectives/index.md b/docs/prevention/objectives/objectives/index.md new file mode 100644 index 00000000..5c04ab88 --- /dev/null +++ b/docs/prevention/objectives/objectives/index.md @@ -0,0 +1,69 @@ +--- +title: Objectives +sidebar_label: Objectives +--- + +# Objectives + +This tab shows every prevention objective individually—all the security goals you're working toward, listed in one place with their current scores and priorities. While the Benchmarks tab organizes objectives by compliance framework, this view lets you see everything flat and search for exactly what you need. + +![Objectives View](./objectives-list.png) + +## What You're Looking At + +Each card is a specific security goal. "Prohibit public access to AWS RDS DB instances" is an objective. "Require MFA for AWS root user authentication" is another. The score tells you how well that objective is being met across your environment—a 5 means excellent coverage, a 0-1 means it's not really being addressed. + +The [priority](/guardrails/docs/prevention/objectives/priorities) badge (P1, P2, P3, or P4) indicates how critical the objective is. P1 objectives are foundational controls that should be in place everywhere. P4 objectives are nice-to-haves that improve security but aren't critical. The [category](/guardrails/docs/prevention/objectives/categories) badge tells you which security domain it belongs to—Identity & Access, Data Governance, Trust & Sharing, and so on. + +This flat view is particularly useful when you know what you're looking for but don't want to navigate through benchmark hierarchies. Search for "encryption" and you'll immediately see all encryption-related objectives with their scores. + +## Finding What You Need + +The search and filter functions are the most useful features here. Search for "MFA" and you'll see all multi-factor authentication objectives. Filter to P1 only and you'll see just the critical objectives. Sort by score (low to high) to find your worst-performing objectives that need attention. + +You can also filter by account to answer questions like "what objectives are we not meeting in the production account?" or filter by category to focus on one security domain at a time. + +## Understanding Scores + +[Objective scores](/guardrails/docs/prevention#prevention-scores) reflect how well you're preventing that specific issue across all applicable accounts. A score of 5 means you have strong preventions in place everywhere. A score of 2-3 means you have partial coverage—maybe some accounts are protected but others aren't, or the preventions you have are weaker than ideal. + +The score takes into account the strength of your preventions (Access layer SCPs score higher than Runtime remediations) and the breadth of coverage (organization-wide preventions count more than account-specific ones). Clicking into an objective shows exactly which preventions are contributing to the score and which accounts still need coverage. + +## Common Use Cases + +- **To verify if you're preventing something** - Search for the relevant term, find the objective, check the score. If it's 4 or 5, yes, you're handling it well. If it's 0-2, no, there's a gap. + +- **When planning security improvements** - Filter to P1 and sort by score to find your highest-priority gaps. These are the critical objectives you're not meeting—your most urgent work. + +- **To identify category imbalances** - Compare average scores across categories. If your Data Governance objectives average 2.5 but your Identity & Access objectives average 4.5, you know where to focus. + +## Objective Detail View + +Clicking any objective opens the Objective Detail page, which provides in-depth information about that single prevention objective—which accounts meet it, which preventions achieve it, implementation recommendations, and CNAPP findings. + +![Objective Detail Page showing tabs and account coverage](./objective-detail.png) + +The Objective Detail page includes: + +**Overview Tab** - Shows a summary explaining what this objective prevents or enforces, why it matters, what risks it mitigates, and how many active preventions achieve this objective. The Account Coverage table shows all accounts and their prevention scores (0-5) for this specific objective, helping you identify which accounts need attention. + +**Preventions Tab** - Lists all preventions achieving this objective. Each entry shows the prevention name, prevention type (SCP, Azure Policy, GCP Organization Policy, or Guardrails control), layer (Build, Access, Config, or Runtime), and implementation status. + +**Recommendations Tab** - Provides actionable guidance including step-by-step implementation instructions, policy templates, cloud provider-specific configurations, prerequisites and dependencies, and testing guidance. Recommendations are prioritized by security impact, compliance requirements, and implementation complexity. + +**Findings Tab** - Shows detections from CNAPP and security scanning tools—which resources currently fail this objective, severity and risk level of each finding, and remediation guidance. Use findings to validate that preventions work as expected and identify resources created before preventions were enabled. + +**Advanced Tab** - Provides technical information for API integration and automation—objective ID and metadata, API endpoints for querying objective status, and GraphQL examples. This tab is primarily for developers integrating prevention data into external systems. + +### Using the Detail View + +To determine why an account has a low score, find the account in the Account Coverage table, check the Preventions tab to see which controls achieve this objective, verify whether those preventions are implemented for that account, and review the Recommendations tab for implementation guidance. + +When implementing an objective across all accounts, review the Summary to understand what it protects, check the Preventions tab for available options, use the Recommendations tab for step-by-step implementation and policy templates, and monitor the Account Coverage table to track rollout progress. + +## Next Steps + +- Review [Priorities](/guardrails/docs/prevention/objectives/priorities) to see objectives grouped by risk level +- Check [Categories](/guardrails/docs/prevention/objectives/categories) to see objectives organized by security domain +- View [Benchmarks](/guardrails/docs/prevention/objectives/benchmarks) to see how objectives map to compliance frameworks +- Visit [Recommendations](/guardrails/docs/prevention/objectives/recommendations) for prioritized implementation guidance diff --git a/docs/prevention/objectives/objectives/objective-detail.png b/docs/prevention/objectives/objectives/objective-detail.png new file mode 100644 index 00000000..f2f5fc00 Binary files /dev/null and b/docs/prevention/objectives/objectives/objective-detail.png differ diff --git a/docs/prevention/objectives/objectives/objectives-list.png b/docs/prevention/objectives/objectives/objectives-list.png new file mode 100644 index 00000000..16e820cf Binary files /dev/null and b/docs/prevention/objectives/objectives/objectives-list.png differ diff --git a/docs/prevention/objectives/priorities/index.md b/docs/prevention/objectives/priorities/index.md new file mode 100644 index 00000000..ebcbc8a4 --- /dev/null +++ b/docs/prevention/objectives/priorities/index.md @@ -0,0 +1,71 @@ +--- +title: Priorities +sidebar_label: Priorities +--- + +# Priorities + +This view groups objectives by their risk level—P1 for critical controls that should be in place everywhere, down to P4 for nice-to-haves. When you're planning security work and need to focus on what matters most, start here. + +![Priorities view showing objectives grouped by priority level](./priorities-view.png) + +## Why Priorities Matter + +Not all security objectives are equally important. "Restrict AWS resources to allowed regions" (P1) is foundational—it enforces data residency and prevents resources from being created in regions you can't monitor or protect. "Require soft delete for Azure File Shares" (P3) is valuable for recovery but not critical to preventing breaches. Priorities help you allocate limited time and resources to the work that reduces the most risk. + +Priority levels reflect the severity of security risk. P1 objectives prevent direct paths to data breaches or service compromise. P2 objectives address significant security or compliance risks. P3 objectives mitigate best practice violations with moderate risk. P4 objectives handle optimization and hygiene issues. + +## The Four Priority Levels + +### P1 - Critical + +P1 objectives are the foundation—controls that should be implemented immediately because they prevent common, severe attacks or are required by virtually every compliance framework. Examples include restricting AWS resources to allowed regions (data residency and compliance), requiring MFA for root user authentication (prevents account takeover), and blocking public access to databases (prevents data breaches). + +These are typically the easiest wins relative to their security value. Restricting resources to specific regions is usually a simple SCP. Blocking public database access is an account setting. The implementation effort is low but the risk reduction is massive. + +If your P1 objectives have low scores, that's your most urgent work. P1 gaps represent fundamental security weaknesses that attackers actively exploit. Most security incidents involve failures of P1-level controls—public S3 buckets, unencrypted databases, resources in unauthorized regions, missing MFA on privileged accounts. + +### P2 - High Priority + +P2 objectives provide strong security improvements and are commonly required by compliance frameworks. They protect sensitive data and prevent common attack vectors. Examples include requiring encryption at rest for EBS volumes, enforcing customer-managed encryption keys, blocking public Lambda functions, and enabling secret scanning in GitHub repositories. + +P2 controls are worth implementing once your P1 foundation is solid. They provide substantial risk reduction and compliance coverage. The implementation might be more complex than P1—requiring encryption might need key management infrastructure, or may require application changes if legacy systems don't support it. + +Most organizations should aim for strong P2 coverage across all accounts within 90 days of establishing P1 baselines. P2 objectives are where you transition from "fundamentally secure" to "well-protected." + +### P3 - Medium Priority + +P3 objectives enhance your security posture through defense-in-depth and operational resilience. They include controls like soft delete for file shares (recovery from accidental deletion), private endpoints for storage (eliminate public exposure entirely), and diagnostic settings for activity logs (support forensics and compliance). + +These controls are valuable but not urgent. They're the difference between "well-protected" and "comprehensively secure." Some organizations implement P3 controls broadly, others focus P3 effort on their most critical workloads and accept the residual risk elsewhere. + +P3 is where you start making conscious tradeoffs based on your specific risk appetite, compliance obligations, and operational capabilities. Not every organization needs the same P3 coverage. + +### P4 - Lower Priority + +P4 objectives are often optimization, hygiene, or industry-specific controls. They provide incremental improvements but aren't critical to preventing breaches. Many organizations never implement all P4 objectives, and that's okay—security is about managing risk to acceptable levels, not achieving perfection. + +P4 objectives make sense when you have mature P1-P3 coverage and are looking for additional hardening, or when they align with specific compliance requirements unique to your industry. + +## Common Use Cases + +- **When planning security work** - Start by filtering to P1 and sorting by score. Any P1 objective with a score below 3 is a critical gap—prioritize those first. Once P1 objectives consistently score 4-5, move to P2. Once P2 is strong, consider P3 selectively based on your environment's needs. + +- **To avoid scattered implementation** - This approach prevents the common mistake of implementing scattered P2 and P3 controls while leaving P1 gaps. A comprehensive set of P3 controls doesn't help if attackers can exploit fundamental P1 weaknesses. + +- **When executives ask "what should we work on next?"** - This view provides data-driven answers. Show them the P1 objectives with low scores, explain the risks, and the work becomes an obvious priority. + +## Balancing Coverage Across Priorities + +[Prevention scores](/guardrails/docs/prevention#prevention-scores) weight priorities using a reverse Fibonacci sequence—P1 objectives have significantly more weight than P4 objectives. This means improving a single P1 objective improves your overall score more than improving multiple lower-priority objectives. The scoring reflects security reality: fixing critical gaps matters more than polishing edge cases. + +Watch for situations where you have strong P3-P4 coverage but weak P1-P2 coverage. This suggests resources are being spent on less important work while fundamental risks remain unaddressed. Rebalance effort toward higher-priority objectives. + +Some organizations set coverage targets: "All P1 objectives must score 4+ across all production accounts. P2 objectives should score 3+. P3-P4 are discretionary." This creates clear expectations and measurable goals. + +## Next Steps + +- Click into any objective to see which preventions implement it and which accounts need coverage +- Review [Benchmarks](/guardrails/docs/prevention/objectives/benchmarks) to see how priorities map to compliance frameworks +- Check [Categories](/guardrails/docs/prevention/objectives/categories) to ensure high-priority objectives are covered across all security domains +- Visit [Recommendations](/guardrails/docs/prevention/objectives/recommendations) to get specific guidance on implementing high-priority objectives diff --git a/docs/prevention/objectives/priorities/priorities-view.png b/docs/prevention/objectives/priorities/priorities-view.png new file mode 100644 index 00000000..e343e2c9 Binary files /dev/null and b/docs/prevention/objectives/priorities/priorities-view.png differ diff --git a/docs/prevention/objectives/recommendations/index.md b/docs/prevention/objectives/recommendations/index.md new file mode 100644 index 00000000..d8ad927c --- /dev/null +++ b/docs/prevention/objectives/recommendations/index.md @@ -0,0 +1,116 @@ +--- +title: Recommendations +sidebar_label: Recommendations +--- + +# Recommendations + +The Recommendations page provides prioritized, actionable guidance for implementing preventions across your cloud environment. This page helps you identify which preventions to implement first based on security impact, compliance requirements, and implementation effort. + +![Recommendations List](./recommendations-list.png) + +## Understanding the Recommendations List + +Recommendations are your prioritized to-do list for improving cloud security. Each one tells you a specific prevention to implement, explains why it matters, and shows you the security impact you'll get. Unlike the Objectives page (which shows what's possible) or the Preventions page (which shows what's already active), Recommendations focuses on what you should do next based on your current gaps. + +Every recommendation has a priority level (P1 through P4) indicating how critical it is, belongs to a security category (like Data Governance or Identity & Access), and includes implementation guidance so you can actually deploy it. The page sorts recommendations by opportunity—considering both the security impact and how many resources currently lack the control—so the most valuable work surfaces first. + +## What Makes This Useful + +The real value of Recommendations is focus. You might have 200 prevention objectives across AWS, Azure, and GCP, but you can't implement everything at once. Which ones matter most right now? Which ones protect the most resources? Which ones address your biggest compliance gaps? Recommendations answers these questions by analyzing your current environment, identifying where you lack preventive controls, and prioritizing what to fix. + +The default sorting—Opportunity (High to Low)—weighs several factors. A P1 objective protecting 50 unprotected accounts ranks higher than a P4 objective protecting 100 accounts. A control required by multiple compliance frameworks you're pursuing ranks higher than one that's not. This intelligent prioritization helps you spend your limited time on work that actually reduces risk rather than randomly picking from a long list of possibilities. + +You can search to find recommendations for specific services ("S3", "Lambda", "Azure Storage"), filter to focus on P1 recommendations or specific accounts, or sort by category to tackle one security domain at a time. The page adapts to how you prefer to work—whether you're chasing compliance certifications, securing specific accounts, or just trying to knock out the highest-impact work each sprint. + +## Recommendation Priorities + +Recommendations are organized by [priority](/guardrails/docs/prevention/objectives/priorities) (P1 through P4) indicating how critical they are. P1 recommendations are foundational controls that prevent common, high-severity attacks and should be implemented immediately. P2 recommendations provide strong security improvements for sensitive data and common attack vectors. P3 recommendations enhance posture through defense-in-depth and operational resilience. P4 recommendations are optimization and hygiene controls that provide incremental improvements. + +Focus on P1 recommendations first—these are often straightforward to implement (a simple SCP or account setting) but provide massive risk reduction. Once your P1 foundation is solid, move to P2. Most organizations should aim for strong P2 coverage within 90 days of establishing P1 baselines. + +## Recommendation Categories + +Recommendations organize by [security domain](/guardrails/docs/prevention/objectives/categories) so you can tackle related controls together or identify imbalanced coverage. The seven categories are Core Infrastructure, Data Governance, Identity & Access, Trust & Sharing, Network Perimeter, Audit & Logging, and Feature Restrictions. + +Filtering to a single category helps when you want to focus effort. Implementing all Data Governance recommendations together often requires similar expertise and tooling, making it more efficient than jumping between unrelated controls. The category view also reveals blind spots—if you have ten P1 Identity & Access recommendations but only two P1 Data Governance recommendations, you might be over-focusing on one domain while neglecting another. + +## Understanding "Opportunity" + +The default sort puts recommendations providing the most security value at the top. Opportunity scoring considers how much risk the prevention reduces (higher-impact controls protecting more resources or preventing more severe threats rank higher), how many accounts or resources currently lack the control (widespread gaps rank higher), whether it's required by compliance frameworks you're pursuing, and how feasible implementation is (easier controls rank higher when they provide similar value to complex alternatives). + +This means a P1 control protecting 50 unprotected accounts typically ranks above a P4 control protecting 100 accounts—the priority weighting recognizes that fixing critical gaps matters more than comprehensive coverage of nice-to-haves. The scoring adapts to your environment, so two organizations might see different top recommendations based on their specific gaps and compliance needs. + +## Recommendation Detail View + +Clicking into any recommendation reveals specific, actionable implementation guidance tailored to your environment. The system generates concrete prevention policies ready to deploy, showing you exactly what to implement and how. + +![Recommendation detail showing generated implementation guidance for EBS volume encryption](./recommendation-detail-overview.png) + +When you open a recommendation like "Implement 'Require encryption at rest for AWS EBS volumes'," the page analyzes your environment and generates specific preventions that will achieve the objective. This isn't generic advice—the recommendations are based on your actual account structure, existing controls, and identified gaps. + +The detail view shows: +- **Summary**: Explains what the objective requires and why it matters—"Require encryption for all EBS volumes to protect block storage data at rest" +- **Current State**: Identifies existing gaps—"Existing rules enforce EBS encryption by default in specific accounts and regions, but not comprehensively across the organization. Gaps include lack of enforcement during CloudFormation operations and incomplete regional settings, risking unencrypted data exposure." +- **Specific Recommendations**: Lists multiple prevention approaches at different layers for defense-in-depth + +Each recommendation includes the complete policy definition or configuration guidance. Expand any recommendation to see the full details: + +![Expanded SCP recommendation showing complete policy JSON and deployment guidance](./recommendation-expanded.png) + +The expanded view shows everything you need to deploy the prevention: +- **How to Deploy**: Specific instructions like "Deploy this SCP at the root level (ID: 369550743463500) to enforce encryption across all AWS accounts in the organization" +- **Complete Policy JSON**: The exact SCP policy document ready to copy +- **Simulate Button**: For SCP recommendations, a button to test the policy before deployment + +You can copy this policy directly into your AWS Organization's SCPs or your Infrastructure-as-Code templates. The recommendations are specific to your environment—they identify the exact organizational units or accounts where the prevention should be deployed based on your current gaps. + +### Testing Recommendations with the Simulator + +For Service Control Policy recommendations, you'll find a "Simulate" button that takes you directly to the [Simulator](/guardrails/docs/prevention/simulator) with the recommended policy pre-loaded. This lets you test the policy against your CloudTrail events before deploying it, ensuring it blocks what you want blocked without breaking legitimate operations. + +![Simulator with pre-loaded SCP policy from recommendation](./recommendation-simulator.png) + +The Simulator workflow: +1. Click "Simulate" on an SCP recommendation +2. The Simulator loads with the recommended policy pre-populated in the URL +3. The policy is ready to test against your organization's structure and CloudTrail events +4. You can verify expected allows and denies before deployment +5. Refine the policy if needed based on test results +6. Deploy with confidence knowing exactly what the policy will do + +This testing capability is critical—SCPs affect entire accounts or OUs, and mistakes can break production systems. The Simulator ensures you understand exactly what the policy will do before you deploy it broadly. You can test against real CloudTrail events from your environment to see which API calls would be allowed or denied, helping you identify any unintended impacts before they affect production. + +## Common Use Cases + +- **When starting a prevention initiative** - Review the default Opportunity sort and focus on P1 recommendations first. Click into each one to understand what objective it achieves, which accounts need it, and how to implement it. Recommendations include policy templates and configuration guidance. Build an implementation plan prioritizing high-opportunity P1 and P2 recommendations, then track progress by watching recommendations disappear as you implement them. + +- **When pursuing compliance certification** - Search for your target framework ("CIS", "NIST", "PCI") and filter to P1 and P2 recommendations. Each recommendation shows which compliance objectives it satisfies, so you can implement controls systematically by benchmark section and track overall compliance progress in the Benchmarks view. + +- **When securing a specific account** - Filter to that account and sort by priority. Knock out P1 recommendations first, then move to P2. Return to the account detail page to see your prevention score improve as you implement controls. + +- **When doing category-focused work** - Filter to a domain like Data Governance or Identity & Access, review all recommendations, and identify patterns. If you see many encryption-related gaps, that's your theme. Implementing category-specific controls together is often more efficient than jumping between unrelated domains since you're using similar expertise and tooling. + +- **When setting monthly security improvement goals** - Implement 5-10 recommendations per sprint, focusing on highest-opportunity recommendations each month. Balance across categories to maintain broad coverage, and track progress by watching total recommendations decrease and prevention scores increase. + +## Tracking Implementation Progress + +As you implement recommendations, they disappear from the list once you've achieved the objective across all applicable accounts. Your prevention scores improve—at the account level, objective level, and benchmark level—reflecting the reduced risk. New recommendations might appear as you add accounts or enable services, and opportunity rankings can shift as your environment evolves, re-prioritizing what provides the most value given your current state. + +Each recommendation includes an impact statement explaining what will be prevented or enforced and why it matters. For example: "Prevent Lambda functions from being invoked by unauthorized principals to prevent unauthorized invocation and data exfiltration. This is critical because public Lambda resource policies can enable unauthorized access, data exfiltration, and abuse of computational resources." These statements help you communicate the security value to stakeholders who might not understand the technical implementation details. + +## Best Practices + +Start with P1 recommendations—critical preventions provide the most security value and are often prerequisites for P2 and P3 controls. For important objectives, implement preventions at multiple layers (Build, Access, Config, Runtime) for defense-in-depth. Consider focusing on one category at a time since implementing all Data Governance recommendations together often requires similar expertise and tooling. + +Use the policy templates provided in recommendations—ready-to-use SCPs, Azure Policies, and other controls accelerate implementation. Always test before deploying broadly—start with a test account, verify the prevention works as expected, then roll out to production. Document any recommendations you choose not to implement, noting why (conflicts with business requirements, alternative control in place, etc.). + +Automate deployment using Infrastructure-as-Code so preventions are consistently applied across accounts and can be version controlled. Return to the Recommendations page regularly—as your environment evolves with new accounts and services, new recommendations will appear, and addressing them promptly prevents security drift. + +## Next Steps + +- Click into any recommendation to see detailed implementation guidance +- Visit [Objectives](/guardrails/docs/prevention/objectives) to understand the security goals behind recommendations +- Check [Preventions](/guardrails/docs/prevention/preventions) to see all active prevention controls +- Review [Accounts](/guardrails/docs/prevention/accounts) to see prevention coverage by account +- Use the [Simulator](/guardrails/docs/prevention/simulator) to test Service Control Policies before deployment diff --git a/docs/prevention/objectives/recommendations/recommendation-detail-overview.png b/docs/prevention/objectives/recommendations/recommendation-detail-overview.png new file mode 100644 index 00000000..ade77748 Binary files /dev/null and b/docs/prevention/objectives/recommendations/recommendation-detail-overview.png differ diff --git a/docs/prevention/objectives/recommendations/recommendation-expanded.png b/docs/prevention/objectives/recommendations/recommendation-expanded.png new file mode 100644 index 00000000..6e51b1e5 Binary files /dev/null and b/docs/prevention/objectives/recommendations/recommendation-expanded.png differ diff --git a/docs/prevention/objectives/recommendations/recommendation-simulator.png b/docs/prevention/objectives/recommendations/recommendation-simulator.png new file mode 100644 index 00000000..06d52d88 Binary files /dev/null and b/docs/prevention/objectives/recommendations/recommendation-simulator.png differ diff --git a/docs/prevention/objectives/recommendations/recommendations-list.png b/docs/prevention/objectives/recommendations/recommendations-list.png new file mode 100644 index 00000000..2da9a05d Binary files /dev/null and b/docs/prevention/objectives/recommendations/recommendations-list.png differ diff --git a/docs/prevention/preventions/index.md b/docs/prevention/preventions/index.md new file mode 100644 index 00000000..607a5688 --- /dev/null +++ b/docs/prevention/preventions/index.md @@ -0,0 +1,46 @@ +--- +title: Preventions +sidebar_label: Preventions +--- + +# Preventions + +The Preventions section provides multiple views of your active preventions, helping you understand what preventive measures are protecting your cloud environment. Each view offers a different perspective on the same preventions—choose the view that best fits your current task. + +![Preventions List](./preventions-list.png) + +## Understanding Preventions + +Preventions are the actual preventive mechanisms implementing your security objectives. While objectives describe what you're trying to achieve (like "prohibit public S3 buckets"), preventions are how you're achieving it—an SCP denying public bucket policies, an S3 Block Public Access account setting, and a Guardrails control remediating public buckets. + +Each prevention has a type (how it's implemented) and a layer (when it operates). Understanding these characteristics helps you choose the right tool for each security objective and build defense-in-depth. + +## Available Views + +The Preventions section provides three different ways to view and analyze your preventions: + +### Preventions Tab + +The [Preventions tab](/guardrails/docs/prevention/preventions/preventions) provides a flat list view with search, filter, and sort capabilities. This is your inventory of active preventions—every Service Control Policy, Azure Policy, account setting, GitHub branch protection rule, and Guardrails control actually running in your environment. + +Use this view when you need to quickly find specific preventions, verify whether a prevention is in place, or see all preventions protecting a particular account. + +### Types Tab + +The [Types tab](/guardrails/docs/prevention/preventions/types) groups preventions by their technical implementation—Service Control Policies, Azure Policies, account settings, GitHub rulesets, and Guardrails controls. This view helps you understand your implementation approach and identify opportunities to simplify or standardize. + +Use this view when you're working with a specific technology, reviewing implementation patterns, or analyzing whether you're over-relying on one type of prevention. + +### Layers Tab + +The [Layers tab](/guardrails/docs/prevention/preventions/layers) organizes preventions by when they operate in the resource lifecycle—Build, Access, Config, or Runtime. This perspective matters for defense-in-depth: critical objectives should have preventions at multiple layers so if one fails, others provide backup. + +Use this view when you're assessing defense-in-depth coverage, planning layer-specific improvements, or identifying objectives that need multi-layer protection. + +## Next Steps + +- Start with the [Preventions tab](/guardrails/docs/prevention/preventions/preventions) to see all your active preventions +- Use the [Types view](/guardrails/docs/prevention/preventions/types) to understand implementation mechanisms +- Review the [Layers view](/guardrails/docs/prevention/preventions/layers) for defense-in-depth assessment +- Check [Objectives](/guardrails/docs/prevention/objectives) to understand which security goals these preventions achieve +- Review [Recommendations](/guardrails/docs/prevention/objectives/recommendations) for implementation guidance diff --git a/docs/prevention/preventions/layers/index.md b/docs/prevention/preventions/layers/index.md new file mode 100644 index 00000000..937f534b --- /dev/null +++ b/docs/prevention/preventions/layers/index.md @@ -0,0 +1,66 @@ +--- +title: Prevention Layers +sidebar_label: Layers +--- + +# Prevention Layers + +Preventions operate at different points in time—some catch problems in your Infrastructure as Code before deployment, others block dangerous API calls, some enforce settings on existing resources, and others respond to threats in real-time. This view organizes your preventions by when they operate, helping you identify whether you have defense-in-depth or are relying too heavily on one approach. + +![Prevention layers showing preventions grouped by enforcement timing](./layers-view.png) + +## Why Layers Matter + +The layer matters because it affects both when problems are caught and how difficult they are to bypass. A Terraform policy that rejects templates defining public S3 buckets (Build layer) catches the issue before anything reaches AWS. An SCP that denies MakeBucketPublic API calls (Access layer) stops the action even if someone tries it manually in the console. An S3 Block Public Access account setting (Config layer) enforces the rule on all buckets regardless of how they were created. A Guardrails control that remediates public buckets (Runtime layer) fixes the problem after it happens. + +Defense-in-depth means having preventions at multiple layers. If your Build layer policies don't catch something (maybe it was created manually), your Access layer SCP should block it. If the SCP has an exception, your Config layer settings should prevent it. If all else fails, your Runtime layer should detect and remediate it. Relying on a single layer leaves you vulnerable if that layer fails or has gaps. + +## The Four Layers + +### Build Layer + +Build layer preventions catch problems in Infrastructure as Code before deployment. A Terraform policy might reject any template that defines an unencrypted RDS instance. A CloudFormation Guard rule might block templates that create public S3 buckets. These preventions operate during CI/CD—before `terraform apply` or `aws cloudformation create-stack` runs. + +The advantage is catching issues earliest with the fastest feedback loop. The developer sees the error immediately, can fix it, and redeploy. The limitation is that Build preventions only protect IaC-managed resources. If someone creates a resource manually through the console, Build layer preventions don't apply. + +Most organizations have limited Build layer coverage because it requires integrating policy enforcement into deployment pipelines. It's easier to implement cloud-native preventions like SCPs or Azure Policies that work regardless of how resources are created. + +### Access Layer + +Access layer preventions block dangerous API calls before they execute. Service Control Policies are the classic example—an SCP that denies `cloudtrail:StopLogging` prevents anyone from stopping CloudTrail, even if their IAM permissions would otherwise allow it. An SCP that restricts `ec2:RunInstances` to specific regions prevents launching EC2 instances in unauthorized regions. + +These preventions are powerful because they cannot be bypassed by account administrators and apply to all principals—users, roles, service accounts, everything. They work whether you're using IaC, the console, CLI, or API. The challenge is they're organization-wide policies that affect everyone, so they require careful testing and exception management. + +Access layer typically has the highest prevention count in most environments because SCPs, Azure Policies with Deny effect, and GCP Organization Policies are widely adopted and relatively straightforward to implement. + +### Config Layer + +Config layer preventions enforce settings on resources that already exist. Account-level settings like S3 Block Public Access prevent buckets from being made public regardless of individual bucket policies. EC2 account attributes can block public AMI sharing. Azure Policies with Modify or DeployIfNotExists effects can automatically fix resource configurations. GitHub branch rulesets prevent force pushes and branch deletion. + +These preventions handle configuration drift—if someone manually changes a resource, Config layer preventions detect and fix it. They apply to all resources in scope, not just new ones. The limitation is they run after resource creation, so there may be a brief window where a resource exists in a non-compliant state before being remediated. + +### Runtime Layer + +Runtime layer preventions respond to threats and misconfigurations during resource operation. Guardrails controls that automatically remediate misconfigured security groups. Lambda functions triggered by CloudWatch Events that respond to suspicious activity. Azure Logic Apps that respond to Defender alerts. + +These preventions catch everything the other layers miss—insider threats, compromised credentials, configuration changes that bypass other preventions, zero-day attack patterns. The limitation is they're reactive rather than preventive—the issue already occurred before the prevention responds. + +## Assessing Your Coverage + +Review the prevention counts for each layer. If you have 50 Access layer preventions but only 2 Config layer preventions, you're heavily reliant on one approach. For critical objectives (P1), aim for preventions at multiple layers. If "prohibit public S3 buckets" is P1, you might want an Access layer SCP denying MakeBucketPublic, Config layer S3 Block Public Access settings, and Runtime layer remediation as backup. + +[Layer weights](/guardrails/docs/prevention#prevention-scores) in scoring reflect their defensive strength—Access layer preventions score highest because they're hardest to bypass and apply most broadly, followed by Config, Runtime, and Build. But don't just optimize for score—a single Access layer SCP with a poorly managed exception can fail, so having Config and Runtime backup preventions provides real security value even if they score slightly lower. + +## Common Use Cases + +- **When building a security program** - Start with Access and Config layers—these provide broad protection with reasonable implementation effort. Add Build layer preventions as you mature your IaC practices. Add Runtime layer preventions for critical assets where additional monitoring and response capabilities provide meaningful risk reduction. + +- **When onboarding new accounts** - Ensure organization-wide Access layer preventions (like SCPs) automatically apply, and replicate key Config layer settings (like S3 Block Public Access) during account provisioning. This gives you baseline protection immediately rather than relying solely on retrofitting Runtime preventions. + +- **When addressing a security gap** - Consider which layer makes the most sense. If the issue is developers deploying non-compliant IaC, add Build layer preventions. If the issue is manual console changes, add Config layer preventions. If the issue is detecting and responding to sophisticated attacks, add Runtime preventions. + +## Next Steps + +- Return to [Preventions](/guardrails/docs/prevention/preventions/preventions) to see all your preventions in one flat list +- Review [Types](/guardrails/docs/prevention/preventions/types) to understand the technical mechanisms at each layer +- Visit [Objectives](/guardrails/docs/prevention/objectives) to see which objectives need multi-layer coverage diff --git a/docs/prevention/preventions/layers/layers-view.png b/docs/prevention/preventions/layers/layers-view.png new file mode 100644 index 00000000..ec06e1ba Binary files /dev/null and b/docs/prevention/preventions/layers/layers-view.png differ diff --git a/docs/prevention/preventions/preventions-list.png b/docs/prevention/preventions/preventions-list.png new file mode 100644 index 00000000..b51208ee Binary files /dev/null and b/docs/prevention/preventions/preventions-list.png differ diff --git a/docs/prevention/preventions/preventions/index.md b/docs/prevention/preventions/preventions/index.md new file mode 100644 index 00000000..739904ab --- /dev/null +++ b/docs/prevention/preventions/preventions/index.md @@ -0,0 +1,67 @@ +--- +title: Preventions +sidebar_label: Preventions +--- + +# Preventions + +This is your inventory of active preventions—every Service Control Policy, Azure Policy, account setting, GitHub branch protection rule, and Guardrails control actually running in your environment. Unlike the objectives view that shows what you're trying to achieve, this shows the preventive mechanisms doing the actual work. + +![Preventions List](./preventions-list.png) + +## What You're Looking At + +Each card represents a live prevention. "Block Public ACLs on AWS S3 Buckets for account goliath-commbank-dev" is a specific prevention applied to a specific account. "Block Force Pushes to Branches" is a GitHub branch protection rule active on your repositories. These aren't aspirational—these are real preventions Guardrails has discovered in your cloud accounts. + +The layer badge (Build, Access, Config, or Runtime) tells you when the prevention operates. The type tells you the technical implementation—an AWS SCP, an Azure Policy, a GitHub ruleset, or an account-level setting. + +## Finding Specific Preventions + +Search is the fastest way to navigate when you have dozens or hundreds of preventions. Search for "S3" to see all S3-related preventions. Search for an account name to see everything protecting that account. Search for "public" to find all preventions preventing public access. + +Filtering becomes useful when you want to see preventions of a specific type or layer. Filter to "AWS S3 Account Setting" to see just those simple account-level toggles. Filter to "Access" layer to see all your SCPs and deny policies. Filter to a specific account when auditing that account's protection. + +![Preventions filtered by S3 search and Access layer](./preventions-search-filter.png) + +You can combine search and filtering for more targeted results. For example, searching for "S3" and filtering to the "Access" layer shows only Access layer preventions (like SCPs) that affect S3 resources, helping you quickly identify which organization-wide policies control S3 operations. + +## Common Use Cases + +- **When investigating why something was blocked** - Search for the service or resource type. If a developer's S3 bucket creation was denied, search for "S3" and review which preventions might have blocked it—maybe an SCP restricting regions, or an account setting blocking public ACLs. + +- **When planning to implement a new prevention** - Search for similar existing preventions first. If you want to add RDS encryption requirements, search for "encryption" to see how you've implemented similar preventions for other services. This consistency makes your security architecture easier to understand and maintain. + +- **When onboarding a new account** - Filter to organization-wide preventions to see what protections automatically apply. Then compare against your target state to identify which account-specific preventions need to be replicated. + +## Prevention Detail View + +Clicking any prevention opens the Prevention Detail page, which provides comprehensive information about that single prevention—showing what it does, which objectives it achieves, what accounts it applies to, and the specific configuration details. + +![Prevention Detail Page showing configuration and matched objectives](./prevention-detail.png) + +The Prevention Detail page shows: + +**Summary Section** - Provides a clear explanation of what the prevention does, the specific behavior being prevented or enforced, the scope of where this prevention applies, and the resource or account context. For example: "This policy enforces encryption for RDS instance and cluster creation operations. It denies the ability to create or restore RDS instances and clusters without encryption, ensuring data protection." + +**Matched Objectives** - Shows which prevention objectives this prevention achieves. Each objective card displays the objective title, type badge, priority level (P1-P4), and current score. This helps you understand the security value this prevention provides and which compliance requirements it satisfies. + +**Configuration Details** - Displays the complete policy definition or configuration—the full JSON for SCPs, policy rules for Azure Policies, constraint configurations for GCP Organization Policies, or control settings for Guardrails controls. You can copy these directly for replication or auditing purposes. + +**Scope and Coverage** - Identifies which accounts or resources are protected by this prevention. Organization-wide preventions show their complete reach across all accounts, while account-specific preventions show exactly which account they protect. + +**Implementation Mechanism** - Shows the prevention type (SCP, Azure Policy, account setting, etc.) and the layer it operates at (Build, Access, Config, Runtime), helping you understand how this prevention fits into your overall defense-in-depth strategy. + +### Using the Detail View + +When investigating why something was blocked, open the prevention detail to see the exact configuration. The policy definition shows you precisely which actions are denied, under what conditions, and with what exceptions. + +When implementing a similar prevention, use the detail view to see how existing preventions are configured. Copy the policy JSON or configuration settings and adapt them for your new use case, ensuring consistency across your security architecture. + +When auditing prevention coverage, check the Matched Objectives section to understand what security goals this prevention achieves. If you're preparing for compliance audits, this helps you map preventive mechanisms to compliance requirements. + +## Next Steps + +- Check [Types](/guardrails/docs/prevention/preventions/types) to understand different prevention mechanisms +- Visit [Layers](/guardrails/docs/prevention/preventions/layers) to assess defense-in-depth coverage +- See [Objectives](/guardrails/docs/prevention/objectives) to understand which security goals these preventions achieve +- Review [Recommendations](/guardrails/docs/prevention/objectives/recommendations) for implementation guidance diff --git a/docs/prevention/preventions/preventions/prevention-detail.png b/docs/prevention/preventions/preventions/prevention-detail.png new file mode 100644 index 00000000..b7218a1f Binary files /dev/null and b/docs/prevention/preventions/preventions/prevention-detail.png differ diff --git a/docs/prevention/preventions/preventions/preventions-list.png b/docs/prevention/preventions/preventions/preventions-list.png new file mode 100644 index 00000000..3acaa092 Binary files /dev/null and b/docs/prevention/preventions/preventions/preventions-list.png differ diff --git a/docs/prevention/preventions/preventions/preventions-search-filter.png b/docs/prevention/preventions/preventions/preventions-search-filter.png new file mode 100644 index 00000000..d65ad780 Binary files /dev/null and b/docs/prevention/preventions/preventions/preventions-search-filter.png differ diff --git a/docs/prevention/preventions/types/index.md b/docs/prevention/preventions/types/index.md new file mode 100644 index 00000000..b0da5fc3 --- /dev/null +++ b/docs/prevention/preventions/types/index.md @@ -0,0 +1,72 @@ +--- +title: Prevention Types +sidebar_label: Types +--- + +# Prevention Types + +Prevention types describe how preventions are technically implemented—Service Control Policies, Azure Policies, account settings, GitHub rulesets, and so on. Each prevention type has different characteristics, tradeoffs, and appropriate use cases. Understanding these helps you choose the right tool for each security objective. + +![Prevention types showing controls grouped by implementation mechanism](./types-view.png) + +## Why Prevention Types Matter + +You could achieve "require encryption for S3 buckets" through an SCP that denies unencrypted uploads, an S3 Bucket Key setting enforcing encryption, or a Guardrails control that remediates non-encrypted buckets. All three accomplish the same objective, but they work differently and have different tradeoffs in complexity, flexibility, and operational characteristics. + +The Types view helps you understand your current approach and identify opportunities to simplify or standardize. If you're implementing similar controls across services using inconsistent mechanisms, standardizing makes your security architecture easier to understand and maintain. + +## Common Prevention Types + +The specific prevention types available depend on which Turbot mods are installed. Below are common types organized by the layer where they typically operate. + +### Build Layer Types + +**AWS CloudFormation Guard Hook** - Custom CloudFormation hooks that enforce preventative guardrails during infrastructure provisioning using Guard DSL validation logic. Hooks evaluate templates at preCreate and preUpdate phases and block non-compliant resources before they are created. Note that hooks only evaluate deployments originating from CloudFormation (including SAM/CDK), not resources created via console, SDKs, or other IaC tools. + +**AWS CloudFormation Lambda Hook** - Custom CloudFormation hooks using Lambda functions for validation logic, providing maximum flexibility for complex validation, external system integration, and custom business rules that cannot be expressed in Guard DSL. Like Guard hooks, these only evaluate CloudFormation deployments. + +**AWS CloudFormation Control Catalog Hook** - References pre-approved CloudFormation hook templates curated by the governance team. The catalog bundles the hook alias, IAM execution roles, and validation logic into reusable artifacts deployed through CloudFormation. + +**AWS Control Tower Proactive Control** - Validates resource configurations during CloudFormation stack creation using CloudFormation hooks. Proactive controls prevent non-compliant resources from being deployed and only affect resources deployed through CloudFormation. + +### Access Layer Types + +**AWS SCP Deny Statement** - Service Control Policy deny rules that explicitly block specific actions across accounts within an AWS Organization. Deny statements create hard barriers by overriding any Allow permissions granted through IAM policies. These apply to all identities within affected accounts, including the account root user, making them powerful for enforcing security baselines like blocking security resource deletion, restricting regions, or preventing security service disablement. + +**AWS SCP Allow Boundary** - Represents the union of all Allow statements from SCPs attached to an Organization Root, OU, or Account. The allow boundary defines what actions are permitted at that specific level before considering the intersection across the organizational hierarchy, providing visibility into permissions granted at each organizational level. + +**AWS RCP Deny Statement** - Resource Control Policies provide resource-level denials to protect specific resources from any principal, including external accounts. RCPs offer more granular control than SCPs by denying actions on specific resources (like S3 buckets or KMS keys) rather than broad service-level restrictions. + +**AWS Control Tower Preventive Control** - High-level rules providing ongoing governance by blocking specific actions before they occur. Can be implemented using SCPs, RCPs, or CloudFormation hooks. These controls create hard barriers affecting entire OUs and every account within the OU. + +### Config Layer Types + +**AWS S3 Account Setting** - Account-level configuration controls establishing security baselines for all S3 buckets within an AWS account. Include S3 Account Public Access Block configurations (BlockPublicAcls, IgnorePublicAcls, BlockPublicPolicy, RestrictPublicBuckets) that prevent public access at the account level, operating uniformly across all regions and buckets. + +**AWS EC2 Account Attribute** - Regional configuration controls establishing security baselines for EC2 resources within each region. Include AMI public access blocking, EBS snapshot public access blocking, default EBS encryption, and internet gateway block mode. Configured per-region but aggregated at account level for unified security posture view. + +**AWS IAM Account Password Policy Option** - Account-level configuration controls establishing password policy and authentication requirements for all IAM users. Include password complexity requirements, password rotation policies, and password reuse prevention, operating uniformly across the entire account. + +### Runtime Layer Types + +**Turbot Guardrails Control** - Provides continuous compliance monitoring and automated remediation for cloud resources across multi-cloud environments. Controls detect configuration drift and non-compliant resources with different enforcement levels: Check (detect and alert), Enforce (automatically remediate), and Skip (disable). Can monitor and enforce settings at multiple levels including account, region, resource type, and individual resources. + +## Prevention in Depth + +Defense-in-depth means implementing multiple prevention types at different layers so if one fails or has gaps, others provide backup protection. For critical objectives, relying on a single prevention type leaves you vulnerable if that prevention has an exception, misconfiguration, or bypass. + +Consider an objective like "prohibit public S3 buckets." You might implement: +- AWS SCP Deny Statement denying public bucket policies (Access layer) - blocks API calls organization-wide +- AWS S3 Account Setting for Block Public Access (Config layer) - enforces settings regardless of bucket policies +- Turbot Guardrails Control for remediation (Runtime layer) - continuously detects and fixes any buckets that become public + +If the SCP Deny Statement has an exception for a specific OU, the S3 Account Settings still protect those accounts. If someone disables the account setting, the Guardrails Control remediates it. Multiple prevention types at multiple layers create redundancy that significantly reduces risk. + +Different prevention types naturally operate at different layers. AWS SCP Deny Statements and AWS RCP Deny Statements operate at the Access layer. AWS S3 Account Settings and AWS EC2 Account Attributes operate at the Config layer. Turbot Guardrails Controls operate at the Runtime layer. This natural alignment makes it easier to build defense-in-depth—implement the objective using prevention types from different layers. + +## Next Steps + +- Return to [Preventions](/guardrails/docs/prevention/preventions/preventions) to see all your controls regardless of prevention type +- Check [Layers](/guardrails/docs/prevention/preventions/layers) to understand when each prevention type typically operates +- Visit [Objectives](/guardrails/docs/prevention/objectives) to see which objectives each prevention type helps achieve +- Review [Recommendations](/guardrails/docs/prevention/objectives/recommendations) for implementation guidance diff --git a/docs/prevention/preventions/types/types-view.png b/docs/prevention/preventions/types/types-view.png new file mode 100644 index 00000000..15894037 Binary files /dev/null and b/docs/prevention/preventions/types/types-view.png differ diff --git a/docs/prevention/simulator/add-draft-scp.png b/docs/prevention/simulator/add-draft-scp.png new file mode 100644 index 00000000..526cae98 Binary files /dev/null and b/docs/prevention/simulator/add-draft-scp.png differ diff --git a/docs/prevention/simulator/add-event-dialog.png b/docs/prevention/simulator/add-event-dialog.png new file mode 100644 index 00000000..62fc0dda Binary files /dev/null and b/docs/prevention/simulator/add-event-dialog.png differ diff --git a/docs/prevention/simulator/add-event-manual.png b/docs/prevention/simulator/add-event-manual.png new file mode 100644 index 00000000..3991584a Binary files /dev/null and b/docs/prevention/simulator/add-event-manual.png differ diff --git a/docs/prevention/simulator/add-event-mock-expanded.png b/docs/prevention/simulator/add-event-mock-expanded.png new file mode 100644 index 00000000..4311b096 Binary files /dev/null and b/docs/prevention/simulator/add-event-mock-expanded.png differ diff --git a/docs/prevention/simulator/add-event-mock-selected.png b/docs/prevention/simulator/add-event-mock-selected.png new file mode 100644 index 00000000..7f3ac142 Binary files /dev/null and b/docs/prevention/simulator/add-event-mock-selected.png differ diff --git a/docs/prevention/simulator/add-event-mock.png b/docs/prevention/simulator/add-event-mock.png new file mode 100644 index 00000000..b7c02526 Binary files /dev/null and b/docs/prevention/simulator/add-event-mock.png differ diff --git a/docs/prevention/simulator/cloudtrail-events-panel.png b/docs/prevention/simulator/cloudtrail-events-panel.png new file mode 100644 index 00000000..288d4645 Binary files /dev/null and b/docs/prevention/simulator/cloudtrail-events-panel.png differ diff --git a/docs/prevention/simulator/index.md b/docs/prevention/simulator/index.md new file mode 100644 index 00000000..8c82499a --- /dev/null +++ b/docs/prevention/simulator/index.md @@ -0,0 +1,173 @@ +--- +title: SCP Simulator +sidebar_label: Simulator +--- + +# SCP Simulator + +The SCP Simulator lets you test Service Control Policies before deploying them to production. Service Control Policies are powerful—they can deny API actions across your entire AWS Organization—but that power makes them risky to deploy without testing. The simulator helps you understand how an SCP will affect your environment, catch unintended consequences, and validate that policies work as expected. + +![SCP Simulator interface showing organization hierarchy, SCPs, and CloudTrail events](./simulator-overview.png) + +## Why Testing SCPs Matters + +Service Control Policies are unusual among AWS controls because they're so broad and so permanent. An SCP attached at your organization root affects every account, every principal, every API call. An SCP deny can't be overridden by an IAM allow—it's absolute. If you deploy an SCP that accidentally denies a critical operation, you've just broken that operation across your entire organization. + +The simulator prevents these mistakes. You can paste an SCP, test it against recent CloudTrail events from your accounts, see what would be blocked, refine the policy, and test again—all without touching production. By the time you deploy, you're confident the SCP does what you intend and nothing more. + +## Understanding SCP Behavior + +SCPs inherit down the organization tree. If you attach an SCP at the organization root, it affects every account. If you attach an SCP to an OU, it affects that OU and all accounts and child OUs beneath it. If any SCP in the hierarchy denies an action, the action is denied—there's no way to override an explicit deny. + +The effective permissions for any API call are the intersection of all SCPs in the hierarchy and the IAM policies. Even if IAM policies allow an action, an SCP can deny it. But SCPs don't grant permissions—they only restrict what IAM policies can grant. + +Most organizations use one of two SCP patterns. The allowlist pattern explicitly allows specific services (like S3, EC2, RDS) and implicitly denies everything else—useful for restricting which AWS services can be used. The denylist pattern explicitly denies specific dangerous actions (like deleting IAM roles or stopping CloudTrail) while allowing everything else—useful for preventing specific risky operations. + +The simulator helps you test both patterns and understand their effects before deployment. You can see which services would be blocked by an allowlist, or which operations would be denied by a denylist, and refine the policy until it matches your intent. + + + +## How to Use the Simulator + +The simulator interface has four main sections that work together to help you test SCPs: + +**[Organization Hierarchy Visualization](#organization-hierarchy-visualization)** - The left panel displays your AWS Organization structure as an interactive graph, showing the organization root, OUs, accounts, and how SCPs flow down through the hierarchy. Use this to understand your organizational structure and see which entities are affected by each SCP. + +**[Service Control Policies Panel](#service-control-policies-panel)** - The middle panel lists all SCPs currently attached to your organization. Here you can view policy details, disable SCPs temporarily for testing, duplicate policies to create variations, and add draft SCPs to test what-if scenarios before deploying to production. + +**[CloudTrail Events Panel](#cloudtrail-events-panel)** - The right panel is where you add CloudTrail events to test against your SCP configuration. You can paste actual CloudTrail event JSON, manually construct API call scenarios, or upload log files containing multiple events. + +**[Evaluation Results](#evaluation-results)** - When you select an event, the simulator evaluates it against all active SCPs and displays whether the action would be allowed or denied, which SCP caused the denial, and the reasoning behind the decision. Denied actions are highlighted visually in the organization diagram. + +### Organization Hierarchy Visualization + +The left panel shows your AWS Organization structure as an interactive graph. You'll see: +- The organization root at the top +- Organizational Units (OUs) organized by hierarchy +- Individual AWS accounts grouped under their respective OUs +- Visual connections showing how SCPs flow down through the hierarchy +- SCP attachment points indicated by connecting lines + +![Simulator showing organization hierarchy with SCP attachments](./simulator-main-view.png) + +You can interact with the graph using the zoom controls (+/-), fit view (⊡), and reset layout (↻) buttons in the bottom left. Use the search bar at the top to quickly find specific accounts or OUs. + +### Service Control Policies Panel + +The middle panel lists all SCPs currently attached to your organization. For each SCP, you can: + +**View SCP Details**: Click "Expand details" on any SCP to see: +- Attachment ID and target (which OU or account it's attached to) +- Status (Active or Disabled) +- Policy statistics: total statements, allow vs. deny statements, whether conditions are present +- Full policy JSON document + +![Full SCP policy JSON displayed in the simulator](./scp-policy-view.png) + +**Actions on existing SCPs**: +- **Disable SCP**: Temporarily disable an SCP to see how it affects your evaluation results +- **Duplicate SCP**: Create a copy to modify and test variations +- **Copy JSON**: Copy the policy document to your clipboard +- **View Full Policy**: Expand to see the complete JSON policy document + +**Add Draft SCPs**: The "Add Draft" button lets you create temporary SCPs to test what-if scenarios. You don't need to deploy these to your actual organization—they exist only in the simulator for testing. + +![Dialog for adding a custom draft SCP with target selection](./add-draft-scp.png) + +When adding a draft SCP, you can: +- Name your policy for easy identification +- Choose the target type: Root, Organizational Unit, or Account +- Select the specific target from a dropdown +- Write or paste your policy JSON +- Use pre-built templates for common scenarios + +![SCP templates including Full Access, Deny Root Access, and Deny Region](./scp-templates.png) + +Available templates include: +- **Full Access**: Allow all actions on all resources (useful as a baseline) +- **Deny Root Access**: Prevent root user from performing actions +- **Deny Region**: Block actions in specific AWS regions + +### CloudTrail Events Panel + +The right panel is where you test SCPs against actual or simulated CloudTrail events. This is how you verify whether API calls would be allowed or denied under your SCP configuration. + +![CloudTrail Events Panel showing added events ready for testing](./cloudtrail-events-panel.png) + +#### Adding Events + +Click the "Add Event" button to open the event creation dialog. The dialog provides multiple ways to add events for testing: + +![Add Event dialog showing available tabs](./add-event-dialog.png) + +##### Adding Events from a File + +Upload JSON files containing CloudTrail event records. The simulator will parse multiple events from the file, allowing you to test a batch of operations at once. This is useful for testing how an SCP would affect recent activity from your production accounts. + +##### Adding Mock Events + +Select from pre-built event templates organized by AWS service and common scenarios. This is the fastest way to test typical API calls without constructing events manually. + +![Mock Events tab showing service categories](./add-event-mock.png) + +Click any service category to expand and see available event templates: + +![Expanded S3 category showing mock event templates](./add-event-mock-expanded.png) + +Select an event template to automatically populate all required fields with realistic values. You can use these values as-is or modify them to match your specific testing scenario: + +![Selected mock event with populated fields](./add-event-mock-selected.png) + +##### Adding Events Manually + +![Manual Entry tab showing fields for constructing custom events](./add-event-manual.png) + +Paste actual CloudTrail event JSON directly from CloudTrail logs (from the AWS Console, CloudWatch Logs Insights, or downloaded log files). The simulator will parse the event and extract the relevant fields (eventName, awsRegion, sourceIPAddress, userIdentity, requestParameters, etc.). + +After adding events, they appear in the events list in the CloudTrail Events panel. Click any event to evaluate it against your current SCP configuration and view the results in the Evaluation Results section. + +### Evaluation Results + +When you select an event from the CloudTrail Events panel, the simulator evaluates it against all active SCPs and displays comprehensive results showing whether the action would be allowed or denied. + +The Evaluation Results panel shows: +- Whether the action would be **Allowed** or **Denied** +- Which SCP caused the denial (if applicable) +- The specific statement within the SCP that matched the action +- The effective permissions chain through the organization hierarchy +- Detailed reasoning for the evaluation decision + +This is particularly valuable when multiple SCPs apply to an account (from the organization root, from parent OUs, and from the account itself), because understanding the combined effect can be challenging. + +#### Viewing Denied Actions + +When an event is denied by an SCP, the simulator provides visual feedback to help you understand exactly why: + +![Simulator showing a denied S3 action with highlighted path and evaluation details](./simulator-denied-1600.png) + +The simulator highlights the evaluation path in the organization diagram, showing: +- **Red highlighting** on the path from the organization root through OUs to the target account +- **The specific SCP** that denied the action (shown in the middle panel) +- **Evaluation Results panel** (right side) displaying: + - The final decision: "Denied" with a red indicator + - Which SCP statement caused the denial (e.g., "Statement S3" in "Data-Compute-Controls" SCP) + - The specific deny rule that matched (e.g., denying `s3:PutObject` without encryption) + - The account and principal that attempted the action + - The full context of the API call + +This visual representation makes it immediately clear which policy is blocking an action and why, helping you quickly identify whether the block is intentional or if the policy needs adjustment. + +## Common Use Cases + +- **When testing a new SCP before deployment** - Draft a policy meant to block dangerous actions or enforce regional restrictions, paste it into the simulator, test it against recent CloudTrail events from accounts that will be affected, and see what would be blocked. If the simulator shows you're about to deny legitimate CloudFormation deployments or CI/CD operations, you refine the policy to add exceptions before any damage is done. + +- **When diagnosing why something's being blocked** - If developers report that an API call is being denied and you suspect an SCP is responsible, recreate the API call in the simulator and see exactly which SCP policy is causing the deny. This helps you understand if the block is intentional (working as designed) or if the policy needs adjustment. + +- **When training team members on SCPs** - SCPs are conceptually different from IAM policies—they only restrict, they inherit down the organization tree, explicit denies can't be overridden. The simulator provides a safe environment to demonstrate these behaviors and let team members experiment without affecting production. + + +## Next Steps + +- Return to [Preventions](/guardrails/docs/prevention/preventions) to see which SCPs are currently deployed +- Review [Objectives](/guardrails/docs/prevention/objectives) to understand which security goals SCPs can achieve +- Visit [Recommendations](/guardrails/docs/prevention/objectives/recommendations) to find SCP policies recommended for your environment diff --git a/docs/prevention/simulator/scp-policy-view.png b/docs/prevention/simulator/scp-policy-view.png new file mode 100644 index 00000000..19f95f60 Binary files /dev/null and b/docs/prevention/simulator/scp-policy-view.png differ diff --git a/docs/prevention/simulator/scp-templates.png b/docs/prevention/simulator/scp-templates.png new file mode 100644 index 00000000..988a2838 Binary files /dev/null and b/docs/prevention/simulator/scp-templates.png differ diff --git a/docs/prevention/simulator/simulator-denied-1600.png b/docs/prevention/simulator/simulator-denied-1600.png new file mode 100644 index 00000000..cae4b2a2 Binary files /dev/null and b/docs/prevention/simulator/simulator-denied-1600.png differ diff --git a/docs/prevention/simulator/simulator-main-view.png b/docs/prevention/simulator/simulator-main-view.png new file mode 100644 index 00000000..91a1c1f9 Binary files /dev/null and b/docs/prevention/simulator/simulator-main-view.png differ diff --git a/docs/prevention/simulator/simulator-overview.png b/docs/prevention/simulator/simulator-overview.png new file mode 100644 index 00000000..1eb522c1 Binary files /dev/null and b/docs/prevention/simulator/simulator-overview.png differ diff --git a/docs/sidebar.json b/docs/sidebar.json index 8080337d..e9b5b17f 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -103,6 +103,62 @@ "getting-started/faq" ] }, + + { + "type": "category", + "id": "prevention", + "link": "prevention", + "items": [ + { + "type": "category", + "id": "prevention/dashboard", + "link": "prevention/dashboard", + "items": [ + "prevention/dashboard/explore", + "prevention/dashboard/reports" + ] + }, + { + "type": "category", + "id": "prevention/accounts", + "link": "prevention/accounts", + "items": [ + "prevention/accounts/accounts", + "prevention/accounts/organizations", + "prevention/accounts/folders", + "prevention/accounts/visualize" + ] + }, + { + "type": "category", + "id": "prevention/objectives", + "link": "prevention/objectives", + "items": [ + "prevention/objectives/benchmarks", + "prevention/objectives/objectives", + "prevention/objectives/priorities", + "prevention/objectives/categories", + "prevention/objectives/recommendations" + ] + }, + { + "type": "category", + "id": "prevention/preventions", + "link": "prevention/preventions", + "items": [ + "prevention/preventions/preventions", + "prevention/preventions/types", + "prevention/preventions/layers" + ] + }, + { + "type": "category", + "id": "prevention/simulator", + "link": "prevention/simulator", + "items": [] + } + ] + }, { "type": "category", "id": "concepts", @@ -256,7 +312,9 @@ "type": "category", "id": "firehose", "link": "guides/configuring-guardrails/firehose", - "items": ["guides/configuring-guardrails/firehose/pipelines"] + "items": [ + "guides/configuring-guardrails/firehose/pipelines" + ] }, { "type": "category", @@ -277,7 +335,6 @@ "guides/configuring-guardrails/policy-packs/attach-policy-pack-to-resource" ] }, - "guides/configuring-guardrails/regions", { "type": "category", @@ -433,7 +490,6 @@ ] }, "guides/hosting-guardrails/FAQ", - { "type": "category", "id": "troubleshooting", @@ -494,7 +550,9 @@ "type": "category", "id": "faq/workspace-faq", "link": "faq/workspace-faq", - "items": ["faq/workspace-faq/key_rotation"] + "items": [ + "faq/workspace-faq/key_rotation" + ] }, "faq/guardrails-and-aws-scps" ] @@ -547,7 +605,9 @@ "type": "category", "id": "reference/terraform", "link": "reference/terraform", - "items": ["reference/terraform/setup"] + "items": [ + "reference/terraform/setup" + ] }, { "type": "category", @@ -582,4 +642,4 @@ "link": "https://turbot.com/guardrails/changelog", "label": "Changelog" } -] +] \ No newline at end of file diff --git a/style.md b/style.md new file mode 100644 index 00000000..0c6e43cc --- /dev/null +++ b/style.md @@ -0,0 +1,359 @@ + +# Documentation Style Guide + +This document provides guidance on writing user documentation for Turbot's public sites, including: + - https://turbot.com/pipes/docs + - https://turbot.com/guardrails/docs + - https://steampipe.io/docs + - https://powerpipe.io/docs + - https://flowpipe.io/docs + +## General + +- Usually, write in the second person (you). Tutorials may occasionally use 3rd person plural to feel collaborative (`Let's get started`, etc).: + - Good: + - `You can save a snapshot by clicking the camera icon` + - `Click the camera icon to save a snapshot` + - `Let's get started` + - Bad: + - `One may save a snapshot by clicking the camera icon` + - `A user can click the camera icon to save a snapshot` + +- Stay in markdown where possible; use HTML only where necessary: + - prefer `![](/link/to/img)` over ``. + - You may need to use the `` tag to specify an image size for an image that is not full screen (like a modal), but for full-screen images, use markdown and don't specify the size. + - use HTML `
` only when you absolutely have to, because all the nested elements then have to be HTML - you cant use markdown inside an HTML table like you can in a markdown table. + +- Prefer example-driven guides and tutorials where people can learn by doing. + - Use progressive disclosure - start with a simple, executable/completable example, then get progressively more complex. + - Where possible, let the example explain the concept. + +- Turn word wrap on in your editor and rely on it for wrapping text instead of putting linefeeds in yourself. + - Grammar checkers and syntax highlighting get confused when linefeeds occur in expected places. + - People edit on different screen sizes. + +## File Names & Directory structure + +- File names, directory names, and slugs should be kebab-case; URLs should use dashes (`-`) instead of underscores (`_`). + - [Google recommends hyphens](https://developers.google.com/search/docs/crawling-indexing/url-structure) for SEO reasons. + - This includes **all** file and directory names for consistency (even images). + +- In general, place files in a directory structure that matches the site structure and sidebar navigation. + - Avoid using the `slug` in the frontmatter in favor of relying on the file and directory naming. + - The directory structure should usually follow the sidebar hierarchy. + +- Store screenshot images in the same directory as the markdown files that use them. + - This approach implies a directory for *every* page that uses screenshots, and that screenshots are no re-used across pages. + - Use relative links for these images - `[](./my-image.png)` + +- Store shared images (icons, etc) in the `/images` directory at the root of the repo. + + +## Navigation bar + +- Use [Title Case](https://capitalizemytitle.com/style/AP/) for sidebar items. +- The navigation bar title should usually match the page title. +- The file path name (and, therefore, the slug) should match the navigation bar. For example, if you have a markdown page titled “Install TE,” the file name should be `install-te`, thus the slug would be `install-te`, so the the URL would be something like `https://www.example.com/install-te.`. + + +## Page Structure + +Generally, each page should start with an h1 (`#`) that matches the page `title` and `sidebar_label` from the metadata, followed by a brief overview. + +### Overview +- The overview should not have its own title - no `## Overview` section header +- The overview is usually only a paragraph or two but may link to other sections. +- Now that we are linking to the section headers from the auto-generated `On This Page`, avoid creating an index via table or bullets in the overview. + - Reference docs are an exception to this rule. Often, a table of the command/var/etc with a brief description makes sense in reference documentation (e.g., https://powerpipe.io/docs/reference/cli/benchmark) + + +### Frontmatter + +- Include `title` and `sidebar_label`. Usually, they should usually be the same: + + ```yaml + --- + title: Install TE + sidebar_label: Install TE + ``` + +- Avoid using the `slug` in the frontmatter in favor of relying on the file and directory naming. + +- Generally, use AP Title case for the title and sidebar label. + - Exceptions for items in reference documentation when titles are commands, environment variables, etc, that are case sensitive, for example: + - [CLI reference](https://powerpipe.io/docs/reference/cli) + - [Environment variable reference](https://powerpipe.io/docs/reference/env-vars) + - [HCL reference](https://powerpipe.io/docs/powerpipe-hcl) + +## Headers +- Every page should have a single h1 (`#`) that generally should match the metadata `title` and `sidebar_label` exactly (including case). + +- Subsequent sub-headers should start at h2 (`##`). +- Sub-headers should be **Title Case**. + +## Bullets +- Text in bulleted lists (and in table columns) should end with a period (`.`) if the items in the list are sentences or sentence fragments (because once you add a second sentence, you need the period): + ```md + This sentence: + - is a sentence fragment. + - is a sentence fragment followed by another sentence. This is the other sentence. + ``` + +- If the bulleted list is just "items", no period is required: + ```md + Elements: + - card + - chart + - query + - control + ``` + +## Tables + +- Use HTML `
` only when you absolutely have to: + - All the nested elements then have to be HTML - you can't use markdown inside an HTML table like you can in a markdown table. + - Sometimes the markdown table formatting is insufficient, and there is no choice, usually when columns wrap weird. +- Follow the guidance in the [bullets](#bullets) section regarding periods. + + +## Images +- Use markdown image syntax (`![](/my/image.png`) instead of `` tag where possible. +- Follow the suggested [guidance for screenshots](#screenshots). + + +## Links + +- Hyperlink to relevant docs, but don't repeat the same link from the same section as it makes the text hard to read. + - Good: + > Powerpipe makes it easy to create your own [controls](https://powerpipe.io/docs/powerpipe-hcl/control) and [benchmarks](https://powerpipe.io/docs/powerpipe-hcl/benchmark). This allows you to define the controls that are important to you and your organization, and organize them into benchmarks that reflect your standards and practices. + - Bad: + > Powerpipe makes it easy to create your own [controls](https://powerpipe.io/docs/powerpipe-hcl/control) and [benchmarks](https://powerpipe.io/docs/powerpipe-hcl/benchmark). This allows you to define the [controls](https://powerpipe.io/docs/powerpipe-hcl/control) that are important to you and your organization, and organize them into [benchmarks](https://powerpipe.io/docs/powerpipe-hcl/benchmark) that reflect your standards and practices. + + +## Examples and Instructions + +In Guides, How To's etc: + +- **Bold** website element labels, e.g., + - Select **Launch product** (Button) + - Select **Update** (It's a Button here) + +- Use `backticks` when referring to the text, e.g., + - Enter `my-volume` in the **Name** field + +- Use `backticks` when referring to code elements, CLI commands, etc. + - For example, "use the `--var` flag to pass a variable." + - This includes constants like CloudFormation states, etc. `CREATE_COMPLETE`, `CREATE_FAILED`. + +- Use code bocks (3 backticks) for commands instead of inlining them when providing examples and instructions. You can inline them when talking about them generally or informally, eg: "Powerpipe benchmarks automatically appear as dashboards when you run `powerpipe server` in the mod." + + +## Code Blocks +- Specify code block type (`json`, `hcl`, `sql`, `bash`, etc) for syntax highlighting. +- Use the standard indenting/formatting we use for the given language (e.g., 2 spaces for tab, align HCL after the `=`, etc.). + + ```json + { + "foo": "bar" + } + ``` + + ```hcl + image { + src = "https://steampipe.io/images/steampipe_logo_wordmark_color.svg" + alt = "Powerpipe Logo" + width = 2 + } + ``` + + + + +## Blockquote Call-Outs (i.e., Tip, Note, Important, Warning & Caution) + +Use the extended [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) blockquote call-out types where appropriate + + +> [!NOTE] +> Used to call out information worth highlighting. +> Highlights crucial information that is necessary for success. +> Contains details that the reader must be aware of to avoid issues. +> Can include warnings, prerequisites, or important clarifications. + +> [!TIP] +> Offers helpful advice or best practices. +> Focuses on enhancing the reader’s experience or efficiency. +> Often contains optional but helpful advice. +> Presented as an extra or nice-to-know piece of information. + +> [!IMPORTANT] +> Highlights critical information that users should not overlook. + +> [!WARNING] +> Alerts users to urgent issues or actions that may cause problems. + +> [!CAUTION] +> Used to warn users about potential risks or negative outcomes. + + +## Screenshots + +- Use light mode for screenshots. +- Screenshots should be PNG images. +- Full-page screenshots should not have a border. +- Modal dial screenshots should show the border because they are not full-width. +- Don't show the whole browser window - omit the toolbar, status bar, etc, and only show the active pane. +- Most screenshots should capture the entire active window area. The recommended size is **1280p** x **640p**. The vertical height may be adjusted if you need to display information that would not appear at that height, but the width should always be 1280. + + +### Device +- Mac laptops are the most common device in Turbot, and are generally preferred when taking screenshots. Use the following display settings: + - Apple XDR Display (P3-1600 nits) + - Default resolution 1512x982 +- If not using a Mac, take the screenshot on a 14" laptop (or something close) and follow the same [directions](#how-to-take-screenshot). + + +### How to take screenshot + +- Use Chrome with 100% zoom. + +- Resize the window: + - Open `Developer Tools`. + - Resize your window until it's **1280p** x **640p** (you can view the pixels in the top right of your window while you're resizing it). + - Note that the size displayed by Developer Tools represents the size of the active content, and closing the `Developer Tools` would expand the width/height of the of the active content to fill the space it currently occupies. Retain developer tools on the right side of the browser to make sure the width **1280p** is maintained. See the image below where the red highlighted portion is fixed at **1280p** but the vertical height has been adjusted to show information which would not be rendered within recommended height of **640p**. + +- Take a screenshot of the browser area you want to capture. You can use the Mac screenshot app tool to capture the screen using `Command` + `Shift` + `5`; the highlighter can be set to the desired width of **1280p** and height of **640p**. + +- When you take a screen capture: + - Always include the full width of the browser window in the screenshot unless the screenshot is only for a modal dialog. + - You may vary the vertical height from the recommended size (640p) to include enough to let users find the elements on their screen easily. + - For example: https://aws.amazon.com/blogs/machine-learning/llm-experimentation-at-scale-using-amazon-sagemaker-pipelines-and-mlflow/ + - Modal windows can be shown alone. + + +### Annotations +Annotations may be used to mark up screenshots in order to provide more precise instructions. Annotations should be reserved for step-wise, instructional content such as [Turbot Guardrails Guides](#writing-turbot-guardrails-guide). + +There are two types of screenshot annotations: +- [Arrows](#arrows) are primarily used to highlight inactive (non-clickable) content. +- [Ovals](#ovals) are used to show where an action should be performed (click a button, tab, etc.) + +You can add annotations with [ksnip](https://github.com/ksnip/ksnip). + + +#### Arrows + +- Use arrows to point to non-clickable content. +- Leave a gap between the arrow and the target (button). +- Arrows should **never** be pointing vertically north/south; they should always be diagonal at 45 degrees. The arrow may face either direction depending on the content position. +- Use an arrow when there is a possibility of ovals overlapping any buttons or text beside it. +- On Mac, use a width of `8`, no shadow. +- On non-Mac screens, use width `16`, no shadow. + +#### Ovals + +- Use **Ovals** to show where the action is to be performed (clicking a button, tab, dropdown, etc.) +- Leave a gap around the target (text). +- On Mac, use a width of `5`, red border, no fill, no shadow +- On non-Mac screens, use width `10`, red border, no fill, no shadow + + +#### Redacting content +Sometimes you may need to redact sensitive content. To do so, you may blur or pixelate the region on the screen. Generally, we prefer **pixelate** to **blur**. + +- Pixelate - 10 weight (Not in use for now) +- Blur - 18 weight + + + +------ +------ + +# Writing Turbot Guardrails Guides + +- Section titles should be 5 words or less. +- Each section should start with a command, e.g., **Launch**, **Create**, **Access**. +- Use `select` when selecting something on screen or `choose` when choosing something from a list/drop down. +- Terms should be linked to the glossary the first time they are used except for the "in this guide, you will" bullets. + +## Guide Sections + +Each guide will have the following sections: +1. An [overview](#guide-overview) +2. [Prerequisites](#prerequisites) +3. One of more [Steps](#step-sections), conccluding with **Monitor** and **Review** steps +4. [Next Steps](#next-steps) +5. [Troubleshooting](#troubleshooting) + + +### Guide Overview + +The overview should apprear immediately after the page title; do not include a `## Overview` header. + +1. State what the user will do with this guide (what you'll do). +2. Provide any additional overview (what is this). +3. Provide 1 to 2 sentences (as long as it explains) about `why does it matter`. + +### Prerequisites + +List any prerequisites with appropriate links + +### Step Sections + +- Each step should have its own h2 header. +- The header format is `Step {number}: Step Title`. + - As always, use title case in the header. + - The step title should begin with a verb. + - examples: + - [`Step 1: Access AWS Console`](https://turbot.com/guardrails/docs/guides/hosting-guardrails/installation/install-te#step-1-access-aws-console) + - [`Step 2: Navigate to Products`](https://turbot.com/guardrails/docs/guides/hosting-guardrails/installation/install-te#step-2-navigate-to-products) + - [`Step 3: Find Version`](https://turbot.com/guardrails/docs/guides/hosting-guardrails/installation/install-te#step-3-find-version) + +- Include a **Monitor** step to inform the user how they can monitor the progress or view the status of the operation. + - Example: [`Step 7: Monitor Installation`](https://turbot.com/guardrails/docs/guides/hosting-guardrails/installation/install-te#step-7-monitor-installation) + +- The final step should be a **Review** step. This should state what should have occurred, as well as a checklist of items to review and verify everything was run successfully. + - Example: [`Step 8: Review`](https://turbot.com/guardrails/docs/guides/hosting-guardrails/installation/install-te#step-8-review) + + +### Next Steps +- Provide links to related guides, Guardrails documentation, or any external reference documentation. + - Example: https://developer.hashicorp.com/terraform/tutorials/configuration-language/test#next-steps + +### Troubleshooting + +Use tabular format e.g. + +| Issue | Description | Guide +|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------- +| Permission Issues | If the current logged-in user lacks permission to modify, update, or create resources in the stack, or if IAM roles or SCPs have changed, preventing built-in roles from accessing needed configuration settings. | [Troubleshoot Permission Issues](/guardrails/docs/enterprise/FAQ/admin-permissions#aws-permissions-for-turbot-guardrails-administrators) +| Further Assistance | If you continue to encounter issues, please open a ticket with us and attach the relevant information to assist you more efficiently. | [Open Support Ticket](https://support.turbot.com)