mswell/dotfiles/plans

JavaScript Code Analysis Skill for Bug Bounty

TL;DR

Quick Summary: Criar uma skill completa de análise de código JavaScript para bug bounty, focada em vulnerabilidades de alto impacto com patterns validados, técnicas de escalação, e Safe Harbor compliance. Estrutura modular seguindo o padrão do security-audit existente.

Deliverables:

- setup/Skills/js-code-analysis/SKILL.md - Skill principal

- scripts/analyze.js, scripts/check_safety.js, scripts/pattern_validator.js - Scripts auxiliares

- references/vulnerability-patterns.md, references/escalation-guide.md, references/h1-examples.md - Documentação de referência

- references/patterns/*.yaml - ast-grep patterns validados

- tests/fixtures/*.js - Code snippets vulneráveis para validação

Estimated Effort: Medium

Parallel Execution: YES - 3 waves (estrutura, scripts, references)

Critical Path: Task 1 (Estrutura) → Task 2-4 (Scripts) → Task 5-7 (References) → Task 8 (Integração)

Context

Original Request

Criar uma nova skill em setup/Skills/ para análise de código JavaScript extraído de aplicações testadas em bug bounty. As vulnerabilidades devem ter impacto real de segurança com PoC funcional. Foco em escalação para aumentar criticidade. Considerar Safe Harbor para plataformas HackerOne, Bugcrowd, Intigriti e YesWeHack.

Interview Summary

Key Discussions:

• Estrutura: Completa (SKILL.md + scripts + references) - similar ao security-audit
• Automação: Apenas análise manual (grep/ast-grep, sem SAST tools)
• Frameworks: Faseado - Express + Next.js primeiro (com fallback para agente especialista se outros frameworks)
• PoC: Exemplos de código apenas (sem scripts completos de exploit)

Research Findings:

• Top 10 JS vulnerabilities by H1 impact identificados (Prototype Pollution, IDOR, SSRF, Command Injection, NoSQL Injection, JWT Issues, PostMessage, Path Traversal, GraphQL, ReDoS)
• Técnicas de escalação documentadas (IDOR→ATO via token leak, XSS→RCE via React2Shell CVE-2025-66478, SSRF→Cloud metadata access)
• Safe Harbor guidelines para todas as plataformas

Metis Review

Identified Gaps (addressed):

• Framework Scope: Faseado para não diluir qualidade - Express + Next.js first, com fallback para especialista
• False Positive Fatigue: Usar ast-grep estrutural, não grep simples
• Safety/Legal: Implementar Safe Harbor check obrigatório em todos os scripts
• Pattern Validation: Incluir test suite com code snippets vulneráveis

Work Objectives

Core Objective

Criar uma skill de análise de código JavaScript especializada em bug bounty, com patterns validados, técnicas de escalação, e compliance Safe Harbor para todas as plataformas principais.

Concrete Deliverables

• setup/Skills/js-code-analysis/SKILL.md - Skill principal com workflow completo
• setup/Skills/js-code-analysis/scripts/analyze.js - Wrapper para ast-grep com filtering inteligente
• setup/Skills/js-code-analysis/scripts/check_safety.js - Safe Harbor verification
• setup/Skills/js-code-analysis/scripts/pattern_validator.js - Valida patterns contra test fixtures
• setup/Skills/js-code-analysis/references/vulnerability-patterns.md - Patterns por categoria (Prototype Pollution, IDOR, SSRF, etc.)
• setup/Skills/js-code-analysis/references/escalation-guide.md - Técnicas de escalação (IDOR→ATO, XSS→RCE, etc.)
• setup/Skills/js-code-analysis/references/h1-examples.md - Exemplos reais do HackerOne com IDs
• setup/Skills/js-code-analysis/references/patterns/*.yaml - ast-grep patterns em YAML
• setup/Skills/js-code-analysis/tests/fixtures/*.js - Vulnerable code snippets para validação

Definition of Done

• [x] Skill invocável via /js-code-analysis ou detecção automática
• [x] Scripts executáveis e retornam help text
• [x] ast-grep patterns validados (sintaxe correta)
• [x] Safe Harbor warning presente em todas as saídas
• [x] Pelo menos 5 vulnerabilidades core com patterns completos

Must Have

• Foco em Express.js e Next.js (maior incidência em bug bounty)
• Safe Harbor check obrigatório (verifica security.txt, programa ativo, etc.)
• ast-grep patterns estruturais (não apenas grep textual)
• Técnicas de escalação para cada vulnerabilidade
• Exemplos reais do HackerOne com H1 IDs

Must NOT Have (Guardrails)

• Scripts de auto-exploit (apenas detecção e PoC manual)
• SELF-XSS ou vulnerabilidades sem impacto real
• Testes destrutivos em produção
• Coverage de todos os frameworks de uma vez (dilui qualidade)
• Ferramentas SAST complexas (Semgrep/CodeQL) - manter foco em análise manual assistida

Verification Strategy (MANDATORY)

Test Decision

• Infrastructure exists: NO (nova skill)
• Automated tests: Tests-after (validar patterns após criação)
• Framework: Node.js built-in + custom validation script

Agent-Executed QA Scenarios (MANDATORY — ALL tasks)

Scenario 1: Verify directory structure exists

Tool: Bash
Preconditions: Working directory is dotfiles repo root
Steps:
  1. ls -la setup/Skills/js-code-analysis/
  2. Assert: SKILL.md, scripts/, references/, tests/ exist
  3. ls setup/Skills/js-code-analysis/scripts/
  4. Assert: analyze.js, check_safety.js, pattern_validator.js exist
Expected Result: Complete directory structure in place
Evidence: Directory listing output

Scenario 2: Verify scripts are executable

Tool: Bash
Preconditions: Node.js available
Steps:
  1. node setup/Skills/js-code-analysis/scripts/check_safety.js --help
  2. Assert: Output contains "Usage:" or "SAFE HARBOR"
  3. node setup/Skills/js-code-analysis/scripts/analyze.js --help
  4. Assert: Output contains "Usage:" or "analyze"
Expected Result: Scripts executable with help text
Evidence: Help output captured

Scenario 3: Verify ast-grep patterns are valid

Tool: Bash
Preconditions: ast-grep (sg) installed, patterns created
Steps:
  1. ls setup/Skills/js-code-analysis/references/patterns/*.yaml
  2. for f in setup/Skills/js-code-analysis/references/patterns/*.yaml; do sg -p $(cat $f) --json 2>&1 | head -1; done
  3. Assert: No "error" or "invalid pattern" in output
Expected Result: All patterns syntactically valid
Evidence: Pattern validation output

Scenario 4: Verify Safe Harbor warning

Tool: Bash
Preconditions: check_safety.js script exists
Steps:
  1. node setup/Skills/js-code-analysis/scripts/check_safety.js --dry-run
  2. Assert: Output contains "SAFE HARBOR" or "security.txt" or "authorization"
Expected Result: Safe Harbor check present in script
Evidence: Script output with warning

Scenario 5: Validate patterns against vulnerable fixtures

Tool: Bash
Preconditions: Pattern validator script and test fixtures exist
Steps:
  1. node setup/Skills/js-code-analysis/scripts/pattern_validator.js --test
  2. Assert: Output contains "PASS" or patterns matched
  3. Assert: No "FAIL" or false negatives
Expected Result: Patterns correctly detect vulnerable code
Evidence: Validator output with test results

Execution Strategy

Parallel Execution Waves

Wave 1 (Start Immediately):
├── Task 1: Create directory structure + SKILL.md skeleton
└── Task 5: Create vulnerability patterns reference
 
Wave 2 (After Wave 1):
├── Task 2: Create analyze.js script
├── Task 3: Create check_safety.js script
├── Task 4: Create pattern_validator.js script
├── Task 6: Create escalation guide reference
└── Task 7: Create H1 examples reference
 
Wave 3 (After Wave 2):
├── Task 8: Create ast-grep patterns (YAML files)
└── Task 9: Create test fixtures + integration
 
Critical Path: Task 1 → Task 2 → Task 8 → Task 9
Parallel Speedup: ~50% faster than sequential

Dependency Matrix

Agent Dispatch Summary

TODOs

• [x] 1. Create Directory Structure + SKILL.md Skeleton

What to do:

• Create setup/Skills/js-code-analysis/ directory
• Create subdirectories: scripts/, references/, references/patterns/, tests/, tests/fixtures/
• Create SKILL.md with frontmatter and skeleton structure:
• name: js-code-analysis
• description: Specialized JavaScript code analysis for bug bounty hunting
• Workflow Overview
• Quick Start section
• Phase structure placeholder
• Include fallback instruction: "Se o código não for Express.js ou Next.js, invoque um agente especialista em segurança web (subagent_type='oracle', load_skills=['security-audit']) para análise customizada."

Must NOT do:

• Não criar conteúdo completo ainda (apenas skeleton)
• Não criar outros arquivos ainda

Recommended Agent Profile:

• Category: quick
• Reason: Simple file/directory creation task
• Skills: []
• No special skills needed for directory creation

Parallelization:

• Can Run In Parallel: YES
• Parallel Group: Wave 1 (with Task 5)
• Blocks: Tasks 2, 3, 4, 8
• Blocked By: None

References:

• setup/Skills/security-audit/SKILL.md:1-50 - Frontmatter and structure pattern to follow
• setup/Skills/AgentsSkillsBugBounty/HYBRID_GUIDE.md - Reference for agent fallback instructions

Acceptance Criteria:

• [x] Directory structure: ls -R setup/Skills/js-code-analysis shows SKILL.md, scripts/, references/, tests/
• [x] SKILL.md has valid frontmatter (name, description fields)
• [x] SKILL.md contains workflow overview section
• [x] Fallback instruction present for non-Express/Next.js code

Agent-Executed QA Scenarios: ``` Scenario: Verify directory structure created Tool: Bash Steps:

1. ls -la setup/Skills/js-code-analysis/
2. Assert: SKILL.md, scripts/, references/, tests/ in output
3. ls setup/Skills/js-code-analysis/references/patterns/
4. Assert: Directory exists (may be empty)

Expected Result: Complete directory structure Evidence: Directory listing output ```

Commit: YES (groups with 5)

• Message: feat(skills): add js-code-analysis skill structure
• Files: setup/Skills/js-code-analysis/

• [x] 2. Create analyze.js Script

What to do:

• Create setup/Skills/js-code-analysis/scripts/analyze.js
• Implement ast-grep wrapper with intelligent filtering
• Support pattern categories: prototype-pollution, idor, ssrf, command-injection, nosql-injection, jwt, postmessage, path-traversal, graphql, redos
• Output format: JSON (for agent parsing) + Markdown summary
• Include Safe Harbor warning at script start
• CLI interface: node analyze.js --target /path/to/code --category idor --format json

Must NOT do:

• Não implementar auto-exploitation
• Não usar ferramentas SAST externas (Semgrep/CodeQL)

Recommended Agent Profile:

• Category: quick
• Reason: Script creation with clear requirements
• Skills: []
• Standard Node.js scripting, no special skills

Parallelization:

• Can Run In Parallel: YES
• Parallel Group: Wave 2 (with Tasks 3, 4, 6, 7)
• Blocks: Task 8
• Blocked By: Task 1

References:

• setup/Skills/security-audit/scripts/detect_project.py - Python script pattern to follow
• Research findings: ast-grep CLI syntax, pattern structure