feat: add security-plan-auditor agent

[omer-demir]

Pull Request

Description

Add security audit expert agent for validating and updating security plans against changed requirements, new features, or updated infrastructure configurations.

Key capabilities:

• Systematic gap analysis between security plans and current state
• Audit category framework with finding severity levels
• Five-phase workflow from scope definition to report generation
• Integration with existing security-plan-outputs directory

Related Issue(s)

Fixes #336

Type of Change

Select all that apply:

Code & Documentation:

• New feature (non-breaking change adding functionality)

AI Artifacts:

• Copilot agent (.github/agents/*.agent.md)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
• See Agents Not Accepted and Model Version Requirements.

Sample Prompts (for AI Artifact Contributions)

"Audit my security plan for the azure-webapp blueprint - we've added a new Redis cache component and updated the authentication flow"

or

"@security-plan-auditor Review the security plan against recent infrastructure changes"

Execution Flow:

1. Phase 1 - Scope Definition: Agent discovers security plans in security-plan-outputs/, presents options, and asks user to select a plan and describe the audit trigger (changed features, new requirements, or infrastructure updates)
2. Phase 2 - Security Plan Analysis: Reads selected security plan, catalogs components, data flows, secrets inventory, and threat mitigations with their statuses
3. Phase 3 - Gap Analysis: Compares security plan against current infrastructure code or requirements, identifies new/removed components, configuration drift, and missing controls
4. Phase 4 - Findings & Recommendations: Presents findings grouped by severity (🔴 Critical, 🟡 Warning, 🟢 Informational), generates remediation recommendations, collects user validation
5. Phase 5 - Report Generation: Creates audit report in security-plan-outputs/ with findings, recommendations, and plan update suggestions

Testing

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (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

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

Additional Notes

This agent complements the existing security-plan-creator.agent.md by providing audit capabilities for existing security plans. While the creator generates new plans from blueprints, the auditor validates existing plans against system changes, ensuring security documentation stays current with evolving infrastructure.

[Copilot]

Pull request overview

This pull request adds a new security-plan-auditor.agent.md agent that complements the existing security-plan-creator.agent.md by providing audit capabilities for existing security plans. The agent validates security plans against system changes such as infrastructure updates, new features, or compliance requirements, identifying gaps and generating actionable remediation recommendations.

Changes:

• Adds conversational security audit agent with five-phase workflow
• Implements systematic gap analysis between security plans and current infrastructure state
• Provides audit category framework and finding severity classification

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 41.04%. Comparing base (672d36b) to head (0605c1a).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #337      +/-   ##
==========================================
- Coverage   41.08%   41.04%   -0.04%     
==========================================
  Files          15       15              
  Lines        2870     2870              
==========================================
- Hits         1179     1178       -1     
- Misses       1691     1692       +1     

Flag	Coverage Δ
pester	41.04% <ø> (-0.04%)	⬇️

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.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[WilliamBerryiii]

Can you add a new line to the end of the file?

[WilliamBerryiii]

@omer-demir this is a really nice baseline review agent ... thanks for the contribution! I'm not sure how the agent would respond to this change, but you may want to reference a few of the core standards like we do in the repo's threat model (probably shouldn't be this specific list - go more generic)

e.g.

[OpenSSF Best Practices Silver Criteria](https://www.bestpractices.dev/en/criteria/1)
[OWASP LLM Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
[MITRE ATLAS](https://atlas.mitre.org/)
[Microsoft Responsible AI Standard](https://www.microsoft.com/ai/responsible-ai)
[STRIDE Threat Model](https://learn.microsoft.com/azure/security/develop/threat-modeling-tool-threats)
[GitHub Security Best Practices](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)

@katriendg and/or @agreaves-ms - can you give this a once over?

[katriendg]

First of all thanks for adding it!

I have a few points at first look at this new agent.

1. I realize we have the security-plan-creator agent which is still quite specific for edge-ai and blueprints. We would like to generalize this one first - can totally be another PR let's just make sure we have a backlog item for this.
2. I understand you have ran prompt-builder agent to validate this agent but maybe you need to update the prompt to make it focus on the generalization of this agent. For example, ask the builder if there are areas of generalization that are possible (blueprints is very specific, not applicable to many repos). Idem for the security baseline, maybe a combination of Bill's list with something like the agent looking up a SECURITY.md file, parse it and analyze if it can find extra security standards. In the care of hve-core it should come up with the repo file about security in our docs folder. Hopefully it gives you some good challenging areas to work on. Wdty?