agent-skill-kit 3.9.135

package/.agent/skills/security-scanner/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: security-scanner
+description: >-
+  Vulnerability analysis: OWASP 2025, supply chain security, and risk prioritization.
+  Use when scanning for vulnerabilities, auditing dependencies, or assessing security risks.
+  NOT for auth implementation (use auth-patterns) or penetration testing (use offensive-sec).
+category: security-auditor
+triggers: ["security", "vulnerability", "OWASP", "pentest", "threat modeling"]
+coordinates_with: ["offensive-sec", "auth-patterns", "cicd-pipeline", "code-review", "problem-checker", "knowledge-compiler"]
+success_metrics: ["Vulnerability Detection Rate", "OWASP Coverage", "Remediation Completeness"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Security Scanner — Vulnerability Analysis & OWASP
+
+> Think like an attacker. Prioritize by exploitability (EPSS), not just severity (CVSS).
+
+---
+
+## 5 Must-Ask Questions (Before Scanning)
+
+| # | Question | Options |
+|---|----------|---------|
+| 1 | Target Assets? | User data / API keys / PII / Financial / Source code |
+| 2 | Threat Actors? | Automated bots / Insider threats / Nation-state / Script kiddies |
+| 3 | Attack Vectors? | Web app / API / Supply chain / Social engineering |
+| 4 | Business Impact? | Data breach / Downtime / Regulatory fines / Reputation |
+| 5 | Compliance Requirements? | GDPR / HIPAA / SOC2 / PCI-DSS / None |
+
+---
+
+## When to Use
+
+| Situation | Approach |
+|-----------|----------|
+| Pre-deployment | Run security scan |
+| New dependencies | Check supply chain (A03) |
+| Code review | Check 5 high-risk patterns |
+| Secret detection | Scan 4 secret categories |
+| Auth implementation | Read `auth-patterns.md` |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| OWASP Top 10:2025 mapping | Red team execution (→ offensive-sec) |
+| Risk prioritization (EPSS + CVSS) | CI/CD configuration (→ cicd-pipeline) |
+| High-risk code patterns (5) | Authentication design (→ auth-patterns) |
+| Secret detection guidance (4 types) | Code fixes |
+
+**Expert decision skill:** Produces vulnerability assessments. Does not run scans.
+
+---
+
+## Core Principles (5 — Fixed)
+
+| Principle | Application |
+|-----------|-------------|
+| **Assume Breach** | Design as if attacker is already inside |
+| **Zero Trust** | Never trust, always verify |
+| **Defense in Depth** | Multiple independent layers |
+| **Least Privilege** | Minimum access required |
+| **Fail Secure** | On error, deny access (fail closed) |
+
+---
+
+## Risk Prioritization (Deterministic)
+
+```
+Is it actively exploited (EPSS > 0.5)?
+├── YES → CRITICAL: Immediate remediation
+└── NO  → Check CVSS score:
+         ├── ≥ 9.0        → HIGH
+         ├── 7.0 - 8.9    → Check asset value → MEDIUM or HIGH
+         └── < 7.0        → LOW: Schedule later
+```
+
+---
+
+## OWASP Top 10:2025 (Fixed)
+
+| Rank | Category | Key Indicators |
+|------|----------|---------------|
+| A01 | Broken Access Control | IDOR, SSRF, privilege escalation |
+| A02 | Security Misconfiguration | Default creds, missing headers |
+| A03 | Supply Chain 🆕 | Compromised deps, CI/CD tampering |
+| A04 | Cryptographic Failures | Weak crypto, exposed secrets |
+| A05 | Injection | String concat in queries, user→commands |
+| A06 | Insecure Design | Missing threat model |
+| A07 | Auth Failures | Broken sessions, weak credentials |
+| A08 | Integrity Failures | Unsigned updates, untrusted pipelines |
+| A09 | Logging & Alerting | Missing audit trail |
+| A10 | Exceptional Conditions 🆕 | Unhandled errors exposing internals |
+
+---
+
+## High-Risk Code Patterns (5 — Fixed)
+
+| Pattern | Risk | Fix |
+|---------|------|-----|
+| String concat in SQL/queries | Injection | Parameterized queries |
+| `eval()`, `exec()` | Remote Code Execution | Remove or sandbox |
+| `pickle.loads()` | Deserialization attack | Use JSON |
+| User input in file paths | Path traversal | Sanitize + allowlist |
+| `verify=False` (SSL) | Security bypass | Enable verification |
+
+---
+
+## Secret Detection (4 Categories)
+
+| Type | Indicators |
+|------|-----------|
+| API Keys | `api_key`, `apikey`, high entropy strings |
+| Tokens | `bearer`, `jwt`, `token` |
+| Credentials | `password`, `secret`, `passwd` |
+| Cloud | `AWS_`, `AZURE_`, `GCP_`, `GOOGLE_` |
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_MISSING_SCORES` | Yes | CVSS/EPSS required for risk |
+| `ERR_INVALID_OWASP` | Yes | Category not A01-A10 |
+| `ERR_INVALID_CVSS` | Yes | CVSS outside 0.0-10.0 |
+
+**Zero internal retries.** Same vulnerability = same classification.
+
+---
+
+## Audit Logging (OpenTelemetry)
+
+| Event | Metadata Payload | Severity |
+|-------|------------------|----------|
+| `scan_started` | `{"scope": "full_audit", "owasp_focus": ["A01", "A05"]}` | `INFO` |
+| `vulnerability_found` | `{"owasp_category": "A05", "pattern": "sql_injection", "file": "src/db.ts"}` | `WARN` |
+| `risk_classified` | `{"severity": "critical", "cvss": 9.8, "epss": 0.7}` | `WARN` |
+| `scan_completed` | `{"findings_total": 8, "critical": 1, "high": 2}` | `INFO` |
+
+All scan outputs MUST emit `scan_started` and `scan_completed` events.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Scan without understanding | Map attack surface first |
+| Alert on every CVE | Prioritize by EPSS exploitability |
+| Fix symptoms only | Address root causes |
+| Trust dependencies blindly | Verify integrity + audit |
+
+---
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [auth-patterns.md](rules/auth-patterns.md) | Authentication patterns | Auth implementation |
+| [checklists.md](rules/checklists.md) | Security checklists | Pre-deployment |
+| [scripts/security_scan.ts](scripts/security_scan.ts) | Scan script | Automated scanning |
+| [engineering-spec.md](rules/engineering-spec.md) | Full spec | Architecture review |
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `cicd-pipeline` | Skill | Pre-deploy integration |
+| `code-review` | Skill | Manual review |
+| `offensive-sec` | Skill | Red team tactics |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/security-scanner/rules/_sections.md

@@ -0,0 +1,15 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/security-scanner/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/security-scanner/rules/auth-patterns.md

@@ -0,0 +1,281 @@
+---
+name: auth-patterns
+description: Authentication security patterns — TOTP 2FA, OAuth2, RBAC, password hashing, session management, rate limiting
+---
+
+# Authentication Security Patterns
+
+> Fail closed. Hash everything. Short-lived tokens. Defense in depth.
+
+---
+
+## Password Hashing
+
+```typescript
+import bcrypt from 'bcrypt'
+
+const SALT_ROUNDS = 12  // Cost factor — higher = slower = more secure
+
+async function hashPassword(password: string): Promise<string> {
+  return bcrypt.hash(password, SALT_ROUNDS)
+}
+
+async function verifyPassword(password: string, hash: string): Promise<boolean> {
+  return bcrypt.compare(password, hash)
+}
+
+// Usage in signup
+async function signup(email: string, password: string) {
+  const hash = await hashPassword(password)
+  await db.user.create({ data: { email, passwordHash: hash } })
+}
+
+// Usage in login
+async function login(email: string, password: string) {
+  const user = await db.user.findUnique({ where: { email } })
+  if (!user || !(await verifyPassword(password, user.passwordHash))) {
+    throw new AuthError('Invalid credentials')  // Same message for both
+  }
+  return generateTokens(user)
+}
+```
+
+---
+
+## JWT Token Strategy
+
+```typescript
+import jwt from 'jsonwebtoken'
+
+const ACCESS_SECRET = process.env.JWT_ACCESS_SECRET!
+const REFRESH_SECRET = process.env.JWT_REFRESH_SECRET!
+
+function generateTokens(user: User) {
+  const accessToken = jwt.sign(
+    { sub: user.id, role: user.role },
+    ACCESS_SECRET,
+    { expiresIn: '15m' }  // Short-lived
+  )
+
+  const refreshToken = jwt.sign(
+    { sub: user.id, jti: crypto.randomUUID() },
+    REFRESH_SECRET,
+    { expiresIn: '7d' }  // Longer-lived, stored in httpOnly cookie
+  )
+
+  return { accessToken, refreshToken }
+}
+
+function verifyAccessToken(token: string) {
+  try {
+    return jwt.verify(token, ACCESS_SECRET) as JwtPayload
+  } catch {
+    throw new AuthError('Invalid or expired token')
+  }
+}
+```
+
+### Session Security Rules
+
+| Rule | Implementation |
+|------|---------------|
+| Store access token | `httpOnly` cookie or memory (never localStorage) |
+| Store refresh token | `httpOnly`, `Secure`, `SameSite=Strict` cookie |
+| Rotate refresh token | Issue new one on each refresh, invalidate old |
+| Logout | Delete both tokens + server-side invalidation |
+
+---
+
+## 2FA TOTP Implementation
+
+```typescript
+import { authenticator } from 'otplib'
+
+// Setup — called once when user enables 2FA
+function setup2FA(userId: string) {
+  const secret = authenticator.generateSecret()
+  const uri = authenticator.keyuri(userId, 'MyApp', secret)
+  // Store secret (encrypted) in DB. Show QR code from uri to user.
+  return { secret, uri }
+}
+
+// Verify — called on every login with 2FA enabled
+function verify2FA(token: string, secret: string): boolean {
+  return authenticator.verify({ token, secret })
+}
+
+// Backup codes — generate on 2FA setup
+function generateBackupCodes(): string[] {
+  return Array.from({ length: 10 }, () =>
+    crypto.randomBytes(4).toString('hex')  // 8-char codes
+  )
+  // Store hashed. Mark used on consumption. One-time only.
+}
+```
+
+---
+
+## Account Lockout
+
+```typescript
+const MAX_ATTEMPTS = 5
+const LOCK_DURATION_MS = 15 * 60 * 1000 // 15 minutes
+
+async function checkLockout(userId: string): Promise<void> {
+  const record = await redis.get(`lockout:${userId}`)
+  if (!record) return
+
+  const { count, lastAttempt } = JSON.parse(record)
+  if (count >= MAX_ATTEMPTS) {
+    const lockExpiry = lastAttempt + LOCK_DURATION_MS
+    if (Date.now() < lockExpiry) {
+      throw new AccountLockedError(lockExpiry)
+    }
+    await redis.del(`lockout:${userId}`)  // Auto-unlock after timeout
+  }
+}
+
+async function recordFailedAttempt(userId: string): Promise<void> {
+  const key = `lockout:${userId}`
+  const record = await redis.get(key)
+  const current = record ? JSON.parse(record) : { count: 0 }
+
+  await redis.setex(key, LOCK_DURATION_MS / 1000, JSON.stringify({
+    count: current.count + 1,
+    lastAttempt: Date.now(),
+  }))
+}
+```
+
+---
+
+## Password Reset Token
+
+```typescript
+import crypto from 'node:crypto'
+
+async function requestPasswordReset(email: string): Promise<void> {
+  const user = await db.user.findUnique({ where: { email } })
+  if (!user) return  // Don't reveal if email exists
+
+  const token = crypto.randomBytes(32).toString('hex')
+  const hashedToken = crypto.createHash('sha256').update(token).digest('hex')
+
+  await db.passwordReset.create({
+    data: {
+      userId: user.id,
+      token: hashedToken,             // Store hashed
+      expiresAt: new Date(Date.now() + 15 * 60 * 1000),  // 15 min
+    },
+  })
+
+  await sendEmail(email, `Reset link: https://app.com/reset?token=${token}`)
+}
+
+async function resetPassword(token: string, newPassword: string): Promise<void> {
+  const hashedToken = crypto.createHash('sha256').update(token).digest('hex')
+
+  const record = await db.passwordReset.findFirst({
+    where: { token: hashedToken, expiresAt: { gt: new Date() } },
+  })
+  if (!record) throw new AuthError('Invalid or expired reset token')
+
+  await db.user.update({
+    where: { id: record.userId },
+    data: { passwordHash: await hashPassword(newPassword) },
+  })
+
+  await db.passwordReset.delete({ where: { id: record.id } })
+  await invalidateAllSessions(record.userId)  // Force re-login
+}
+```
+
+---
+
+## RBAC (Role-Based Access Control)
+
+```typescript
+// Define roles and permissions
+const PERMISSIONS = {
+  admin:   ['read', 'write', 'delete', 'manage_users'],
+  editor:  ['read', 'write'],
+  viewer:  ['read'],
+} as const
+
+type Role = keyof typeof PERMISSIONS
+type Permission = (typeof PERMISSIONS)[Role][number]
+
+// Middleware — check permission before route handler
+function requirePermission(permission: Permission) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const user = req.user  // From auth middleware
+    if (!user) return res.status(401).json({ error: 'Unauthorized' })
+
+    const userPermissions = PERMISSIONS[user.role as Role] || []
+    if (!userPermissions.includes(permission)) {
+      return res.status(403).json({ error: 'Forbidden' })
+    }
+    next()
+  }
+}
+
+// Usage
+app.delete('/api/users/:id', requirePermission('manage_users'), deleteUser)
+app.put('/api/posts/:id', requirePermission('write'), updatePost)
+app.get('/api/posts', requirePermission('read'), listPosts)
+```
+
+---
+
+## Rate Limiting
+
+```typescript
+import rateLimit from 'express-rate-limit'
+
+// General API rate limit
+const apiLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,  // 15 min
+  max: 100,                   // 100 requests per window
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: 'Too many requests, try again later' },
+})
+
+// Strict limit for auth endpoints
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 5,                     // 5 login attempts per 15 min
+  skipSuccessfulRequests: true,
+})
+
+app.use('/api/', apiLimiter)
+app.use('/api/auth/login', authLimiter)
+app.use('/api/auth/reset', authLimiter)
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Store passwords as plain text or MD5 | bcrypt/argon2 with cost ≥ 12 |
+| JWT in localStorage | `httpOnly` cookie |
+| Same error for "user not found" vs "wrong password" visible to attacker | Same generic error for both |
+| Unlimited login attempts | Rate limit + account lockout |
+| Long-lived access tokens | 15 min access + 7 day refresh |
+| Skip 2FA for admins | Require 2FA for elevated roles |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [checklists.md](checklists.md) | Pre-deployment checklist |
+| [scripts/security_scan.ts](scripts/security_scan.ts) | Automated scanning |
+| [SKILL.md](SKILL.md) | OWASP 2025 mapping |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/security-scanner/rules/checklists.md

@@ -0,0 +1,186 @@
+---
+name: security-checklists
+description: Security audit checklists — OWASP 2025, API security, auth, data protection, headers with implementation code
+---
+
+# Security Checklists
+
+> Copy relevant checklists into PLAN.md or security report. Use alongside security_scan.ts.
+
+---
+
+## OWASP Top 10:2025 Checklist
+
+### A01: Broken Access Control
+- [ ] Authorization on all protected routes
+- [ ] Deny by default (fail closed)
+- [ ] Rate limiting on all endpoints
+- [ ] CORS properly configured (no wildcard + credentials)
+- [ ] IDOR protection (validate resource ownership)
+
+### A02: Security Misconfiguration
+- [ ] Debug mode disabled in production
+- [ ] Default credentials changed
+- [ ] Error messages sanitized (no stack traces)
+- [ ] Security headers configured (see below)
+- [ ] Unnecessary features/ports disabled
+
+### A03: Supply Chain 🆕
+- [ ] Lock file committed (package-lock.json / pnpm-lock.yaml)
+- [ ] `npm audit` or `pnpm audit` passes
+- [ ] CI/CD pipeline uses pinned dependencies
+- [ ] No `postinstall` scripts from untrusted packages
+- [ ] Dependency integrity verified (checksums)
+
+### A04: Cryptographic Failures
+- [ ] Passwords hashed (bcrypt cost ≥ 12 or argon2)
+- [ ] Sensitive data encrypted at rest (AES-256)
+- [ ] TLS 1.2+ enforced for all connections
+- [ ] No secrets in code, logs, or version control
+- [ ] Key rotation policy in place
+
+### A05: Injection
+- [ ] Parameterized queries (no string concat)
+- [ ] Input validation on all user data
+- [ ] Output encoding for XSS prevention
+- [ ] No `eval()`, `exec()`, or dynamic code execution
+- [ ] CSP header blocks inline scripts
+
+### A06: Insecure Design
+- [ ] Threat modeling completed
+- [ ] Business logic validated
+- [ ] Abuse cases documented
+- [ ] Security requirements defined
+
+### A07: Auth Failures
+- [ ] MFA available for all users
+- [ ] Session invalidation on logout
+- [ ] Session timeout (15 min access, 7 day refresh)
+- [ ] Brute force protection (lockout + rate limit)
+- [ ] Password policy enforced (min 8 chars, no common passwords)
+
+### A08: Integrity Failures
+- [ ] CI/CD pipeline secured (branch protection, signed commits)
+- [ ] Dependency integrity verified
+- [ ] Update mechanism uses signatures
+- [ ] Build artifacts are reproducible
+
+### A09: Logging & Alerting
+- [ ] Security events logged (login, failed auth, access denied)
+- [ ] Logs protected from tampering
+- [ ] No sensitive data in logs (passwords, tokens, PII)
+- [ ] Alerting configured for suspicious activity
+- [ ] Audit trail for admin actions
+
+### A10: Exceptional Conditions 🆕
+- [ ] All errors handled gracefully
+- [ ] No internal details exposed in error responses
+- [ ] Unhandled exceptions don't crash the application
+- [ ] Error monitoring configured (Sentry, etc.)
+
+---
+
+## Security Headers Implementation
+
+### Next.js (next.config.js)
+
+```javascript
+const securityHeaders = [
+  { key: 'Content-Security-Policy', value: "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'" },
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'X-XSS-Protection', value: '1; mode=block' },
+  { key: 'Strict-Transport-Security', value: 'max-age=31536000; includeSubDomains' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
+]
+
+module.exports = {
+  async headers() {
+    return [{ source: '/(.*)', headers: securityHeaders }]
+  },
+}
+```
+
+### Express Middleware
+
+```typescript
+import helmet from 'helmet'
+
+app.use(helmet())  // Sets all security headers automatically
+
+// Or manual:
+app.use((req, res, next) => {
+  res.setHeader('Content-Security-Policy', "default-src 'self'")
+  res.setHeader('X-Content-Type-Options', 'nosniff')
+  res.setHeader('X-Frame-Options', 'DENY')
+  res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
+  res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin')
+  next()
+})
+```
+
+### Header Reference
+
+| Header | Purpose | Value |
+|--------|---------|-------|
+| `Content-Security-Policy` | XSS prevention | `default-src 'self'` |
+| `X-Content-Type-Options` | MIME sniffing | `nosniff` |
+| `X-Frame-Options` | Clickjacking | `DENY` |
+| `Strict-Transport-Security` | Force HTTPS | `max-age=31536000; includeSubDomains` |
+| `Referrer-Policy` | Referrer control | `strict-origin-when-cross-origin` |
+| `Permissions-Policy` | Feature access | `camera=(), microphone=()` |
+
+---
+
+## Quick Audit Commands
+
+```bash
+# Dependencies
+npm audit                             # Node.js vulnerabilities
+npm audit --audit-level=high          # Only high+ severity
+pnpm audit                            # pnpm equivalent
+pip-audit                             # Python dependencies
+
+# Secrets
+npx secretlint "**/*"                 # Scan for secrets
+git log --all -p | grep -i "password\|api_key\|secret"  # Git history
+
+# Code patterns
+npx eslint --rule 'no-eval: error' .  # Detect eval()
+grep -rn "dangerouslySetInnerHTML" src/  # XSS vectors
+
+# Full scan (this skill)
+node .agent/skills/security-scanner/scripts/security_scan.ts . --output=summary
+
+# HTTPS/TLS
+openssl s_client -connect example.com:443  # Check TLS version
+curl -I https://example.com | grep -i "strict\|content-security\|x-frame"  # Headers
+```
+
+---
+
+## CI/CD Security Checklist
+
+- [ ] Branch protection on `main` (require PR + approvals)
+- [ ] Secrets stored in CI/CD variables (not in repo)
+- [ ] Dependencies scanned on every PR (`npm audit`)
+- [ ] SAST (Static Analysis) runs on every commit
+- [ ] No `--force` push to protected branches
+- [ ] Build environment isolated (ephemeral containers)
+- [ ] Deployment requires manual approval for production
+- [ ] Artifact signing enabled
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [auth-patterns.md](auth-patterns.md) | Auth implementation |
+| [scripts/security_scan.ts](scripts/security_scan.ts) | Automated scanning |
+| [SKILL.md](SKILL.md) | OWASP 2025 mapping, risk prioritization |
+
+---
+
+⚡ PikaKit v3.9.134