fix(skills): add AST validation and namespace restriction for content-extra.py

[WilliamBerryiii]

Description

Addressed a critical CWE-94 vulnerability in the PowerPoint skill where content-extra.py scripts were loaded and executed via importlib without any validation. The build_deck.py script now enforces two independent security layers before running user-provided content-extra scripts.

The original build_slide() function called importlib.util.spec_from_file_location() on arbitrary Python files with no restrictions, allowing code injection through malicious content-extra.py scripts.

AST-based static analysis was added to inspect every Import, ImportFrom, and Call node in the script before execution. The validator rejects 34 blocked stdlib modules (covering network, filesystem, code execution, and import machinery surfaces), 5 dangerous builtins (eval, exec, __import__, compile, breakpoint), and 6 indirect-bypass builtins (getattr, setattr, delattr, globals, locals, vars). Only pptx and safe stdlib modules pass the import allowlist; all other third-party packages are rejected by default.

Runtime namespace restriction strips the dangerous and indirect-bypass builtins from the module's __builtins__ dict before execution, creating a defense-in-depth layer that catches patterns the AST checker might miss. __import__ is intentionally preserved in the runtime namespace because Python's import machinery depends on it internally — the AST checker compensates by blocking direct __import__() calls.

An --allow-scripts CLI flag was added as an opt-in escape hatch for trusted content. When passed, both AST validation and namespace restriction are skipped entirely. The flag propagates through all three build_slide() call sites in main().

The SKILL.md documentation was updated with a "Security Validation" subsection documenting the allowed/blocked imports, blocked builtins, runtime namespace behavior, and --allow-scripts usage.

Related Issue(s)

Fixes #1017

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

"Build a PowerPoint deck from the content directory with security validation enabled."

Execution Flow:

1. User runs python scripts/build_deck.py --content-dir content/ --style content/global/style.yaml --output presentation.pptx
2. For each slide directory containing a content-extra.py, the build script calls _validate_content_extra() to parse the script AST and check all imports and builtins against the allowed sets.
3. If validation passes, the script runs in a restricted namespace with dangerous builtins stripped from __builtins__.
4. If validation fails, ContentExtraError is raised with a message identifying the violation and file path.
5. To bypass validation for trusted content, pass --allow-scripts.

Output Artifacts:

The build produces a PowerPoint file at the specified output path. No additional files are created by the security validation.

Success Indicators:

• Build completes without ContentExtraError for scripts using only safe imports and builtins.
• Scripts with blocked imports or builtins are rejected with clear error messages.
• --allow-scripts bypasses validation for trusted content.

Testing

• Added TestContentExtraValidation class with tests covering valid imports (pptx, safe stdlib), blocked module imports (subprocess, os, os.path, shutil, socket, ctypes), third-party rejection, all 5 dangerous builtins, all 6 indirect-bypass builtins (parametrized), syntax errors, build_slide() integration, allow_scripts bypass, and runtime namespace restriction (both blocked and safe builtins).
• Added TestAllowScriptsCLI class with end-to-end tests through main() verifying --allow-scripts flag propagation and default validation enforcement.
• All 560 tests pass. Ruff clean.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

• Used /prompt-analyze to review contribution
• Addressed all feedback from prompt-builder review
• Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.92%. Comparing base (4309e10) to head (6904953).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1027      +/-   ##
==========================================
- Coverage   86.02%   85.92%   -0.11%     
==========================================
  Files          30       30              
  Lines        5410     5428      +18     
==========================================
+ Hits         4654     4664      +10     
- Misses        756      764       +8     

Flag	Coverage Δ
pester	85.92% <ø> (-0.11%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.