memory-journal-mcp 7.7.0 → 8.0.0

package/skills/adversarial-security/references/multi-pass-security-protocol.md

@@ -0,0 +1,403 @@
+# Multi-Pass Security Protocol
+
+Detailed reference for the 4-phase adversarial security audit workflow. Read
+this when executing the protocol for the full review dimensions, scoring
+system, and output templates.
+
+## Phase 1 — Reconnaissance (Agent A: Threat Modeler)
+
+### Inputs
+
+Before starting the reconnaissance, gather context from these sources:
+
+1. **Repository structure** — directory layout, entry points, transports,
+   data flows, and build configuration
+2. **Existing security documentation** — `SECURITY.md`, security checklists,
+   threat models, and compliance references
+3. **Prior audits** — search the journal for related security entries:
+   ```
+   search_entries({
+     query: "<repository name> security",
+     entry_type: "security_recon",
+     tags: ["adversarial-security"]
+   })
+   ```
+4. **Dependency manifest** — `package.json`, `package-lock.json`,
+   `Dockerfile`, and CI workflow files
+5. **Project type** — auto-detect or use the explicit `PROJECT_TYPE` setting
+   (see SKILL.md § Auto-Detection)
+
+### Reconnaissance Structure
+
+Produce a Markdown document with these sections:
+
+```markdown
+# Security Reconnaissance — [Repository Name]
+
+## Project Profile
+
+- **Type**: [auto-detected or explicit: mcp-server, web-app, cli-tool, library]
+- **Language/Runtime**: [e.g., TypeScript/Node.js 24]
+- **Transports**: [e.g., stdio, HTTP, SSE]
+- **Auth Model**: [e.g., OAuth 2.1, bearer token, none]
+- **Dependencies**: [total count, direct vs. transitive]
+- **CI/CD**: [e.g., GitHub Actions, 13 workflows]
+
+## Trust Boundaries
+
+Diagram or list of trust boundaries:
+
+- External → Server (HTTP transport, MCP protocol)
+- Server → Database (SQL queries, file operations)
+- Server → Sandbox (Code Mode execution)
+- [etc.]
+
+## Attack Surface Map
+
+For each entry point, document:
+
+- Entry point name and location (file:line)
+- Input type (user query, HTTP request, MCP tool call, etc.)
+- Validation present (Zod schema, parameterized query, etc.)
+- Auth required (scope, role, none)
+
+## Existing Defenses (per Category)
+
+For each of the 10 audit categories (see audit-categories.md):
+
+- What defenses are in place
+- Coverage assessment: full / partial / none
+- Evidence: file paths and code references
+
+## Threat Model Summary
+
+| Threat         | Entry Point         | Existing Defense                                | Coverage |
+| -------------- | ------------------- | ----------------------------------------------- | -------- |
+| SQL injection  | sqlite_read_query   | Parameterized queries + identifier sanitization | Full     |
+| Code execution | sqlite_execute_code | vm sandbox + blocked patterns + timeout         | Partial  |
+| [etc.]         |                     |                                                 |          |
+
+## Gaps Identified
+
+Preliminary list of areas where defenses appear weak or absent.
+These are hypotheses — Agent B will validate or refute them.
+```
+
+### Journal
+
+```
+create_entry({
+  content: "<full reconnaissance>",
+  entry_type: "security_recon",
+  tags: ["adversarial-security", "recon"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Phase 2 — Red Team Review (Agent B: Red Team)
+
+Switch mental models. You are now an attacker whose job is to break every
+defense documented in Phase 1. Do not trust the Threat Modeler's coverage
+assessments — verify them by attempting to construct attack scenarios.
+
+### Review Dimensions
+
+Score each dimension on a 1–5 scale. Dimensions have different weights
+reflecting their relative importance for security:
+
+| Dimension             | Weight | Focus Areas                                                                                              |
+| --------------------- | ------ | -------------------------------------------------------------------------------------------------------- |
+| **Exploitability**    | 4      | Attack complexity, privileges required, user interaction needed, remote vs. local, automation potential  |
+| **Impact**            | 3      | Confidentiality (data breach), integrity (data tampering), availability (DoS), privilege escalation, RCE |
+| **Existing Defenses** | 2      | Are mitigations effective? Can they be bypassed? Are there defense-in-depth layers?                      |
+| **Detection**         | 1      | Would exploitation be caught by logging, monitoring, CI gates, or audit trails?                          |
+
+### Severity Mapping (CVSS-Inspired)
+
+| Weighted Score | Severity | Meaning                                                                        |
+| -------------- | -------- | ------------------------------------------------------------------------------ |
+| 4.0–5.0        | Critical | Exploitable remotely with low complexity, high impact, no effective mitigation |
+| 3.0–3.9        | High     | Exploitable with moderate complexity or auth, significant impact               |
+| 2.0–2.9        | Medium   | Requires specific preconditions or has limited blast radius                    |
+| 1.0–1.9        | Low      | Theoretical risk, defense-in-depth improvement, hardening recommendation       |
+
+### Depth Profiles
+
+The `AUDIT_DEPTH` configuration controls which categories and dimensions
+receive full scrutiny:
+
+- **Recon**: Categories 2 (Secrets), 3 (Injection), 4 (Auth) only. Focus on
+  Exploitability + Impact dimensions. Best for quick triage.
+- **Standard**: All 10 categories at stated weights. Default for most audits.
+- **Paranoid**: All 10 categories + extended analysis:
+  - Git history scanning for previously committed secrets
+  - Prototype pollution chain analysis across dependency tree
+  - ReDoS pattern analysis on all regex in codebase
+  - Timing attack surface analysis on comparison operations
+  - Supply chain deep dive (install scripts, typosquatting checks)
+  - Cross-project ecosystem impact assessment
+
+### Critique Output Format
+
+```markdown
+## Red Team Review — [Repository Name]
+
+**Overall Security Score:** [weighted average] / 5.0
+**Posture Grade:** [A–F]
+
+### Grading Scale
+
+| Grade | Score Range | Meaning                                                        |
+| ----- | ----------- | -------------------------------------------------------------- |
+| A     | 4.5–5.0     | Excellent — minimal risk, defense-in-depth present             |
+| B     | 3.5–4.4     | Good — no critical issues, some hardening opportunities        |
+| C     | 2.5–3.4     | Acceptable — medium-risk issues present, remediations needed   |
+| D     | 1.5–2.4     | Poor — high-risk issues found, immediate action required       |
+| F     | 1.0–1.4     | Failing — critical vulnerabilities, deployment not recommended |
+
+### Findings
+
+| #   | Category         | Severity | CWE     | Finding                                 | File:Line     | Exploitability         | Remediation             |
+| --- | ---------------- | -------- | ------- | --------------------------------------- | ------------- | ---------------------- | ----------------------- |
+| 1   | Input Validation | Critical | CWE-89  | SQL interpolation in dynamic query      | src/foo.ts:42 | Remote, no auth        | Use parameterized query |
+| 2   | Auth             | High     | CWE-862 | Endpoint accessible without scope check | src/bar.ts:88 | Remote, auth bypass    | Add hasScope() guard    |
+| 3   | Docker           | Medium   | CWE-250 | Container runs as root                  | Dockerfile:1  | Local, post-compromise | Add USER directive      |
+| ... |                  |          |         |                                         |               |                        |                         |
+
+### Dimension Scores
+
+| Dimension         | Score | Weight | Weighted             |
+| ----------------- | ----- | ------ | -------------------- |
+| Exploitability    | [1–5] | 4      | [score × 4]          |
+| Impact            | [1–5] | 3      | [score × 3]          |
+| Existing Defenses | [1–5] | 2      | [score × 2]          |
+| Detection         | [1–5] | 1      | [score × 1]          |
+| **Total**         |       | **10** | **[sum]/50 = [avg]** |
+
+### Category Breakdown
+
+| Category            | Findings | Worst Severity | Coverage   |
+| ------------------- | -------- | -------------- | ---------- |
+| 1. Dependencies     | 0        | —              | ✅ Full    |
+| 2. Secrets          | 1        | Low            | ✅ Full    |
+| 3. Input Validation | 2        | Critical       | ⚠️ Partial |
+| ...                 |          |                |            |
+
+### Blocking Issues
+
+List any findings that MUST be addressed before deployment or release.
+These are non-negotiable — they represent exploitable vulnerabilities
+with high impact.
+
+### Attack Scenarios
+
+For each critical/high finding, provide a concrete attack scenario:
+
+#### Scenario: [Finding Title]
+
+- **Attacker profile**: [External unauthenticated / Authenticated user / Admin]
+- **Attack vector**: [Step-by-step exploitation path]
+- **Preconditions**: [What must be true for the attack to work]
+- **Impact**: [What the attacker achieves]
+- **Proof of concept**: [Concrete example, payload, or code snippet]
+```
+
+### Journal
+
+```
+create_entry({
+  content: "<full red team critique>",
+  entry_type: "security_redteam",
+  tags: ["adversarial-security", "redteam"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Phase 3 — Remediation Plan (Agent A: Threat Modeler)
+
+Switch back to the Threat Modeler role. Address every finding from the red
+team review with an explicit disposition.
+
+### Disposition Table
+
+For each finding, record one of:
+
+| Disposition | Meaning                                                             |
+| ----------- | ------------------------------------------------------------------- |
+| **Accept**  | Implement the suggested remediation                                 |
+| **Reject**  | Explain why the finding does not apply or is acceptable risk        |
+| **Modify**  | Accept the finding but implement a different remediation            |
+| **Defer**   | Acknowledge the risk but defer to a future milestone (must justify) |
+
+### Remediation Plan Output
+
+Produce the remediation plan prioritized by risk (exploitability × impact):
+
+```markdown
+## Remediation Plan — [Repository Name]
+
+### Disposition Summary
+
+| #   | Finding           | Severity | Disposition | Rationale                                      |
+| --- | ----------------- | -------- | ----------- | ---------------------------------------------- |
+| 1   | SQL interpolation | Critical | Accept      | Will switch to parameterized query             |
+| 2   | Auth bypass       | High     | Modify      | Using middleware guard instead of inline check |
+| 3   | Root container    | Medium   | Defer       | Tracked in issue #42, post-v2 milestone        |
+
+### Quick Wins (< 1 hour each)
+
+Remediations that can be implemented immediately with minimal risk:
+
+| #   | Finding | Fix | Effort |
+| --- | ------- | --- | ------ |
+| ... | ...     | ... | ...    |
+
+### Architectural Changes
+
+Remediations requiring design work or multi-file changes:
+
+| #   | Finding | Approach | Files Affected | Effort |
+| --- | ------- | -------- | -------------- | ------ |
+| ... | ...     | ...      | ...            | ...    |
+
+### Accepted Risks
+
+Findings explicitly rejected or deferred with justification:
+
+| #   | Finding | Disposition | Justification | Review Date |
+| --- | ------- | ----------- | ------------- | ----------- |
+| ... | ...     | ...         | ...           | ...         |
+
+### Updated Security Score
+
+After applying proposed remediations:
+
+- **Before**: [score] / 5.0 (Grade [X])
+- **After (projected)**: [score] / 5.0 (Grade [Y])
+```
+
+### Iteration Control
+
+After remediation planning, check: has `MAX_AUDIT_PASSES` been reached?
+
+- **No** → return to Phase 2 for another red team review of the remediation
+  plan itself (does the fix introduce new vulnerabilities? Are there gaps in
+  the remediation?)
+- **Yes** → proceed to Phase 4
+
+The default of 2 passes means: 1 initial red team + 1 review of the
+remediation plan. For most repositories this is sufficient. Increase for
+high-stakes production systems or compliance-critical codebases.
+
+### Journal
+
+```
+create_entry({
+  content: "<remediation plan with dispositions>",
+  entry_type: "security_remediation",
+  tags: ["adversarial-security", "remediation"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Phase 4 — External Validation (GitHub CLI)
+
+If `COPILOT_VALIDATION` is enabled (default: `true`) and `gh copilot` is
+available, invoke it for an independent review of the audit findings and
+remediation plan.
+
+See [copilot-security-prompts.md](copilot-security-prompts.md) for prompt
+templates, correct CLI syntax, and parsing guidance.
+
+> **⚠️ CRITICAL**: You MUST use `gh copilot -p "<prompt>"` (non-interactive
+> mode). Do NOT use `gh copilot explain` which is interactive and will hang.
+> Always `Set-Location` to the target repository before invoking. Include
+> `--allow-tool "shell(find,cat,head,grep)"` so Copilot can read source files.
+
+> **⚠️ NO FABRICATION**: You MUST actually execute the `gh copilot` commands
+> and report their real output. Do NOT fabricate or predict Copilot findings.
+> If the command fails or is unavailable, skip Phase 4 and document why.
+
+After the Copilot pass, any new findings follow the same disposition process
+from Phase 3. The final audit report is then presented to the user.
+
+If `gh copilot` is not available, skip this phase gracefully and note:
+
+```markdown
+> **Phase 4 skipped**: `gh copilot` not available. The audit completed with
+> internal adversarial review only (Phases 1–3). Install the GitHub CLI and
+> authenticate (`gh auth login`) for external validation.
+```
+
+### Journal
+
+```
+create_entry({
+  content: "<copilot findings + final dispositions>",
+  entry_type: "security_copilot",
+  tags: ["adversarial-security", "copilot"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Final Report Assembly
+
+After all phases complete, produce a consolidated report artifact. This is
+the primary deliverable for the user.
+
+```markdown
+# Adversarial Security Audit — [Repository Name]
+
+**Date**: [ISO date]
+**Audit Depth**: [recon | standard | paranoid]
+**Project Type**: [auto-detected type]
+**Passes Completed**: [N]
+**External Validation**: [yes | skipped]
+
+## Executive Summary
+
+[2–3 sentence summary: overall posture, critical findings count, and
+recommended immediate actions]
+
+**Security Score**: [X] / 5.0 — Grade [A–F]
+
+## Findings Summary
+
+| Category        | Critical | High | Medium | Low | Total |
+| --------------- | -------- | ---- | ------ | --- | ----- |
+| 1. Dependencies | 0        | 0    | 0      | 0   | 0     |
+| 2. Secrets      | ...      |      |        |     |       |
+| ...             |          |      |        |     |       |
+| **Total**       |          |      |        |     |       |
+
+## Top 3 Urgent Remediations
+
+1. [Most critical finding + remediation]
+2. [Second most critical]
+3. [Third most critical]
+
+## Full Findings (by severity)
+
+[All findings from Phase 2, grouped by severity descending]
+
+## Remediation Plan
+
+[From Phase 3 — disposition table + quick wins + architectural changes]
+
+## Accepted Risks
+
+[Findings explicitly deferred with justification and review dates]
+
+## Appendix: Reconnaissance
+
+[Condensed version of Phase 1 output — project profile, trust boundaries,
+attack surface map]
+```

package/skills/adversarial-skill-audit/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: adversarial-skill-audit
+description: |
+  Multi-pass adversarial quality audit for agent skill directories. Combines
+  structured evaluation with adversarial stress-testing to assess skill completeness,
+  instruction clarity, trigger accuracy, and security. Use when auditing a skills directory.
+---
+
+# Adversarial Skill Audit
+
+A multi-pass quality auditing system for agent skill directories. Evaluates
+each skill against the `skill-builder` quality standards through structured
+profiling and adversarial stress-testing — finding gaps in trigger coverage,
+instruction clarity, progressive disclosure, security, and cross-skill
+coherence.
+
+## When to Load
+
+Load this skill when any of these apply:
+
+- Auditing an entire skills directory for quality and consistency
+- Reviewing a batch of skills before publishing or distributing
+- The user asks for skill quality review, audit, or improvement suggestions
+- The user says "audit my skills", "skill quality check", "review these
+  skills", "check my skills", "how good are my skills", or "validate these skills"
+- Preparing a skills directory for npm packaging or distribution
+- You want to identify redundant, incomplete, or poorly triggered skills
+
+## Adversarial Protocol
+
+This skill follows the standard dual-agent adversarial pattern (Agent A: The Evaluator, Agent B: The Adversarial User).
+For the core pipeline rules, phase definitions, and agent switching protocols, read:
+**[../adversarial-security/references/adversarial-base-protocol.md](../adversarial-security/references/adversarial-base-protocol.md)**
+
+For the skill audit-specific protocol with scoring and templates, read:
+**[references/multi-pass-skill-protocol.md](references/multi-pass-skill-protocol.md)**
+
+## Audit Categories
+
+The 8 quality categories evaluated per skill:
+
+1. Frontmatter & Triggering
+2. Instruction Clarity
+3. Structure & Progressive Disclosure
+4. Output Formats & Templates
+5. Edge Cases & Error Handling
+6. Security & Safety
+7. Token Efficiency
+8. Maintenance & Versioning
+
+Additionally, 4 **directory-level** categories assess the collection:
+
+9. Cross-Skill Coherence
+10. Trigger Collision Detection
+11. Coverage Gap Analysis
+12. Ecosystem Consistency
+
+For the full checklist, read
+[references/audit-categories.md](references/audit-categories.md).
+
+## External Validation (Phase 4)
+
+Phase 4 triggers an independent validation pass using the GitHub CLI (`gh copilot`).
+The `copilot` subcommand is built into modern `gh` CLI — no separate extension is
+needed. This provides a fundamentally different model's perspective on skill
+quality, catching issues that internal review normalizes.
+
+For prompts, read
+[references/copilot-skill-prompts.md](references/copilot-skill-prompts.md).
+
+**Prerequisites:** `gh` CLI v2.x+ with `gh auth status` passing. If `gh copilot`
+is not available, skip Phase 4 gracefully and note the skip in the journal entry.
+
+Read [references/copilot-usage.md](references/copilot-usage.md) for critical non-interactive execution requirements.
+
+## Feedback Loop
+
+Every phase creates a journal entry for future retrieval. For templates and
+tag conventions, read
+[references/feedback-loop.md](references/feedback-loop.md).
+
+## Scripts
+
+This skill includes automated helper scripts located in the `scripts/` directory:
+
+- `scripts/check-skills.ps1`: Automated Phase 1 metric gathering (token count, trigger detection).
+- `scripts/run-copilot.ps1`: Automated Phase 4 Copilot validation pipeline.
+
+## Configuration
+
+| Variable             | Default    | Description                                       |
+| -------------------- | ---------- | ------------------------------------------------- |
+| `MAX_AUDIT_PASSES`   | `2`        | Maximum stress-test cycles (phases 2–3 repeat)    |
+| `AUDIT_DEPTH`        | `standard` | Depth: `surface`, `standard`, or `thorough`       |
+| `COPILOT_VALIDATION` | `true`     | Enable/disable Copilot extension validation phase |
+| `INCLUDE_REFERENCES` | `true`     | Whether to read and evaluate reference files too  |
+
+### Audit Depth Profiles
+
+- **Surface**: Frontmatter + structure only (Categories 1, 3, 7). Quick
+  scan for obvious issues. Best for large directories (30+ skills).
+- **Standard**: All 8 per-skill categories + 4 directory-level categories.
+  Default for most audits.
+- **Thorough**: Full audit + extended analysis:
+  - Read every reference file and evaluate its quality
+  - Construct 3 test prompts per skill and evaluate trigger likelihood
+  - Analyze description keyword coverage against real user phrasing
+  - Compare against `skill-builder/checklist.md` item by item
+  - Check for stale content (outdated API references, deprecated tools)
+
+## Synergies
+
+| Skill/Workflow            | Relationship                                                 |
+| ------------------------- | ------------------------------------------------------------ |
+| `skill-builder`           | Defines the quality standards this skill audits against      |
+| `adversarial-planner`     | Parent pattern — plan-level adversarial review               |
+| `adversarial-security`    | Sibling — audits security posture; this audits skill quality |
+| `adversarial-performance` | Sibling — audits performance; this audits skill quality      |