Cursor rule doc1 - Testing cursor validation

.cursor/rules/README.md

@@ -0,0 +1,39 @@
+# Turbot Markdown Validator Pack
+
+## Includes
+
+- ✅ `.cursorrules` to guide Cursor AI generation
+- ✅ Custom markdownlint rules to enforce doc format
+- ✅ GitHub Action to validate PRs
+- ✅ Works with pre-commit if needed
+
+## Setup
+
+1. Copy to your repo root:
+   - `.cursorrules`
+   - `.markdownlint.json`
+   - `.markdownlint/custom-turbot-markdown-rules.js`
+   - `.github/workflows/markdown-lint.yml`
+
+2. Install markdownlint locally (optional):
+```bash
+npm install -g markdownlint-cli2
+```
+
+3. Run validation:
+```bash
+markdownlint-cli2 '**/*.md'
+```
+
+4. See GitHub PR checks run automatically
+
+**Note:** Here the workflow is designed to only capture the changed .md file.
+
+ What `markdown-lint-pr-only` Does?
+
+   - Runs only on Pull Requests to main
+   - Installs markdownlint-cli2
+   - Detects .md files changed in the PR
+   - Lints only those files using your custom
+   rules
+   - Skips unrelated or legacy .md files

.cursor/rules/guide-cursor-rule.mdc

@@ -0,0 +1,10 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+"description": "All guides must use a standardized markdown structure with # title and ## sub-headers.",
+"Use '# Title' followed by a high-level overview.",
+"Include '## Prerequisites' if applicable.",
+"Each major step should be a '## Step X: Description'.",
+"End with '## Troubleshooting' and '## Next Steps' if relevant."

.cursorrules

@@ -0,0 +1,11 @@
+{
+  "description": "Ensure all Turbot Guardrails docs follow a consistent markdown guide format.",
+  "rules": [
+    "Start with YAML frontmatter containing 'title' and 'sidebar_label'.",
+    "Use a single '# Title' after frontmatter.",
+    "Include '## Prerequisites' section if applicable.",
+    "Steps must be formatted as '## Step X: <Action>' in order.",
+    "Optionally include '## Troubleshooting' and '## Next Steps'.",
+    "Use Markdown image embeds and clear step-based headers."
+  ]
+}

.github/workflows/markdown-lint-all

@@ -0,0 +1,18 @@
+name: Markdown Lint
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - run: npm install -g markdownlint-cli2
+      - name: Run markdownlint
+        run: markdownlint-cli2 '**/*.md' '#node_modules'

.github/workflows/markdown-lint-pr-only.yml

@@ -0,0 +1,33 @@
+name: Markdown Lint
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Install markdownlint
+        run: npm install -g markdownlint-cli2
+
+      - name: Get changed markdown files
+        id: changed-files
+        uses: tj-actions/changed-files@v41
+
+      - name: Run markdownlint on changed files
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          echo "${{ steps.changed-files.outputs.all_changed_files }}" | tr ' ' '\n' | grep '\.md$' > changed-files.txt || true
+          if [ -s changed-files.txt ]; then
+            markdownlint-cli2 --config .markdownlint.json $(cat changed-files.txt)
+          else
+            echo "No markdown files changed."
+          fi

.markdownlint.json

@@ -0,0 +1,8 @@
+{
+  "default": true,
+  "MD025": false,
+  "MD013": false,
+  "custom-rules": [
+    "./.markdownlint/custom-turbot-markdown-rules.js"
+  ]
+}

.markdownlint/custom-turbot-markdown-rules.js

@@ -0,0 +1,21 @@
+module.exports = {
+  names: ["TG002", "Turbot-Guide-Structure"],
+  description: "Validate markdown structure for Guardrails installation guides",
+  tags: ["structure", "guide", "guardrails"],
+  function: function(params, onError) {
+    const text = params.lines.join("\n");
+
+    const checks = [
+      { name: "YAML frontmatter", regex: /^---[\s\S]*?---/, message: "Missing or incorrect YAML frontmatter" },
+      { name: "Main title", regex: /^#\s+.+/, message: "Missing '# Title' header" },
+      { name: "Prerequisites", regex: /##\s+Prerequisites/, message: "Missing '## Prerequisites' section" },
+      { name: "Step headers", regex: /##\s+Step\s+\d+:\s+.+/, message: "No '## Step X:' formatted headers found" }
+    ];
+
+    checks.forEach(check => {
+      if (!check.regex.test(text)) {
+        onError({ lineNumber: 1, detail: check.message });
+      }
+    });
+  }
+};

docs/guides/aws/aws-sidebar.json

@@ -34,6 +34,12 @@
       "items": ["guides/aws/permissions/user-mode"]
     },
     "guides/aws/security-hub",
-    "guides/aws/decommission"
+    "guides/aws/decommission",
+    {
+      "type": "category",
+      "id": "controls",
+      "link": "guides/aws/controls",
+      "items": ["guides/aws/controls/s3-bucket-approved"]
+    }
   ]
-}
+}

docs/guides/aws/controls/index.md

@@ -0,0 +1,12 @@
+---
+title: AWS Controls
+sidebar_label: Controls
+---
+
+# AWS Controls
+
+This section contains documentation for various AWS controls available in Turbot Guardrails. These controls help you manage and enforce policies across your AWS resources.
+
+## Available Controls
+
+- [S3 Bucket Approved](s3-bucket-approved) - Manage and enforce approval policies for S3 buckets

docs/guides/aws/controls/s3-bucket-approved/index.md

@@ -0,0 +1,69 @@
+---
+title: AWS S3 Bucket Approved Control
+sidebar_label: S3 Bucket Approved
+---
+
+# AWS S3 Bucket Approved Control
+
+The AWS S3 Bucket Approved control helps you manage and enforce approval policies for your S3 buckets. This control checks the status of defined Approved sub-policies and takes enforcement actions when buckets are not approved.
+
+## Prerequisites
+
+- Access to Turbot Guardrails with AWS integration configured
+- Appropriate AWS permissions to manage S3 buckets
+- Understanding of S3 bucket management in AWS
+
+## Step 1: Understanding the Control
+
+The Approved control evaluates S3 buckets against the following sub-policies:
+- Usage policies
+- Custom policies
+- Region policies
+- Budget policies
+
+When a bucket is not approved according to these policies, the control can:
+- Raise alarms
+- Take enforcement actions
+- Delete unapproved buckets (if configured for new resources)
+
+## Step 2: Configuring the Control
+
+To configure the S3 Bucket Approved control:
+
+1. Navigate to the AWS > S3 > Bucket > Approved policy in your Turbot Guardrails workspace
+2. Set the desired enforcement level:
+   - Skip
+   - Check
+   - Enforce
+   - Delete unapproved if new
+
+## Step 3: Setting Up Sub-policies
+
+Configure the following sub-policies to define approval criteria:
+
+1. **Usage Policies**: Define approved usage patterns
+2. **Custom Policies**: Set custom approval rules
+3. **Region Policies**: Specify approved regions
+4. **Budget Policies**: Set budget constraints
+
+## Step 4: Monitoring and Enforcement
+
+Monitor the control through:
+- Controls by Resource report
+- Controls by Control Type report
+- Alarms and notifications
+
+## Troubleshooting
+
+Common issues and solutions:
+- **Control not triggering**: Verify AWS permissions and policy configurations
+- **False positives**: Review and adjust sub-policy criteria
+- **Enforcement not working**: Check enforcement level settings
+
+## Next Steps
+
+- Review other S3 bucket controls for comprehensive management
+- Set up automated notifications for control violations
+- Configure additional approval policies as needed
+
+For more information, visit the [AWS S3 Bucket Approved Control documentation](https://hub.guardrails.turbot.com/mods/aws/controls/aws-s3/bucketApproved).