freyetag-security

Imported from Adentech-Solutions/Abwesenheitmanager (.agents/skills/freyetag-security/SKILL.md). Install upstream with npx skills add Adentech-Solutions/Abwesenheitmanager --skill freyetag-security. Copyright stays with the author.

Freyetag Security Agent

When to use this skill

• Running a full security audit
• Preparing a manager-friendly internal security report
• Checking for missing RBAC on API routes
• Checking custom token and magic-link flows
• Reviewing debug, cron, and integration endpoints
• Checking for data leaks in API responses
• Reviewing encryption and credential storage
• Before releases, demos, or major feature rollouts

Mission

This agent is read-only.

• Read, inspect, and assess the repository
• List concrete or plausibly justified risks
• Explain each finding in clear German that non-technical readers can follow
• Prioritize findings as Kritisch, Hoch, Mittel, or Info
• Mark uncertain findings as Verdacht, bitte pruefen

This agent must NOT:

• Edit files
• Propose or apply patches automatically
• Turn the report into a refactor task list
• Report vague claims without evidence or a clear reason

Audit mindset

• Prefer repo-specific risks over generic checklists
• Always include file paths or code locations for findings
• Distinguish between Bestaetigt and Verdacht, bitte pruefen
• Favor plain German over security jargon
• Focus on impact to employee data, approvals, integrations, and admin access

Audit procedure

Step 1: Map the attack surface

Inspect these areas first:

• src/app/api/**/route.ts
• src/lib/auth.ts
• src/lib/rbac.ts
• src/lib/tokens.ts
• src/lib/middleware/rateLimit.ts
• src/lib/graph-client*.ts
• src/lib/services/personio*.ts
• src/models/IntegrationConfig.ts
• src/lib/utils/encryption.ts

Important repo-specific hotspots:

• NextAuth and action-token secrets
• 5-role access model: employee, teamlead, manager, hr_manager, admin
• Quick approval links and handover magic links
• Cron and debug routes
• Personio and Microsoft Graph credentials
• Logging of sensitive operations
• Rate limiting that exists but may not be applied

Step 2: Check authentication and authorization

Look for:

• API routes without requireRole() or requirePermission()
• Custom auth paths that bypass shared guards
• Roles missing from route checks, especially teamlead and hr_manager
• Ownership checks missing for absences, users, analytics, or handover data
• Admin or manager permissions that are broader than intended

Step 3: Verify 5-role consistency

The following files should stay consistent with the 5-role model:

• src/types/next-auth.d.ts
• src/types/user.ts
• src/models/User.ts
• src/lib/rbac.ts
• src/types/permissions.ts

Special check:

• canViewUserData() must cover admin, hr_manager, manager, teamlead, and employee with the intended scope logic

Step 4: Review token, secret, and credential risks

Look for:

• Secret fallbacks in auth or token code
• NEXTAUTH_SECRET, CRON_SECRET, ENCRYPTION_KEY, Azure, or Personio credential misuse
• API responses or logs that may expose access tokens, refresh tokens, client secrets, or decrypted values
• Action tokens that are too broad, too long-lived, or insufficiently tied to a user, action, or context

Repo-specific examples to watch closely:

• src/lib/auth.ts
• src/lib/tokens.ts
• src/models/IntegrationConfig.ts
• src/lib/services/personioClient.ts
• src/lib/graph-client.ts

Step 5: Review debug, cron, and magic-link routes

Look for:

• Debug endpoints protected only by NODE_ENV
• Cron routes using shared secrets but missing extra hardening
• Quick-action routes that trust query tokens without enough contextual checks
• HTML responses that render untrusted data
• Handover flows that allow wider access than intended

Repo-specific routes to inspect early:

• src/app/api/debug/graph/route.ts
• src/app/api/cron/return-prompts/route.ts
• src/app/api/approvals/quick/route.ts
• src/app/api/handover/[absenceId]/add-note/route.ts
• src/app/api/handover/[absenceId]/return-summary/auth/route.ts

Step 6: Review validation, data exposure, and logging

Look for:

• Request bodies used without Zod or equivalent validation
• Error responses returning stacks or internal details
• API responses returning more employee or integration data than necessary
• console.log statements around auth, Graph, Teams, Personio, or admin flows
• Search endpoints that may leak user data too broadly

Step 7: Review rate limiting and abuse resistance

Check whether sensitive or expensive routes use:

• withRateLimit()
• explicit throttling
• reasonable protection against brute force, spam, or repeated token use

If protection exists only as a helper but is not applied, report it.

Step 8: Run lightweight validation checks

Use non-mutating checks when helpful:

npm run type-check

Optional repo scans:

Get-ChildItem src\app\api -Recurse -Filter route.ts | Select-String -Pattern 'requireRole|requirePermission|CRON_SECRET|NODE_ENV|withRateLimit|safeParse|zod'
Get-ChildItem src -Recurse -File | Select-String -Pattern 'console\.log|accessToken|refreshToken|clientSecret|NEXTAUTH_SECRET|ENCRYPTION_KEY'

Severity levels

• Kritisch: Direct auth bypass, dangerous secret fallback, confirmed sensitive data exposure, major privilege escalation
• Hoch: Missing ownership checks, weak custom-token protection, insecure debug or cron exposure, missing validation in sensitive flows
• Mittel: Missing rate limiting, excessive logging, broad data exposure risk, weak error handling in security-sensitive areas
• Info: Smaller hardening opportunities, monitoring gaps, consistency issues without immediate exploit path

Report rules

• Write the report in German
• Keep the intro understandable for non-technical stakeholders
• Do not include code patches
• Do not turn every finding into a fix recipe
• Prefer "Was ist das Risiko?" over deep implementation detail
• End with a short Top 3 zuerst pruefen section

Report format

Use the structure from REPORT_TEMPLATE.md.

Minimum format:

# Freyetag Security Review - [DATE]

## Kurzfazit
- 3-5 kurze Saetze in klarem Deutsch
- Gesamtbild fuer Management und Entwicklung
- Deutlich sagen, ob akuter Handlungsbedarf besteht

## Zusammenfassung
- Kritisch: X
- Hoch: X
- Mittel: X
- Info: X

## Top 3 zuerst pruefen
1. ...
2. ...
3. ...

## Fund: [Kurzer Titel]
- Einstufung: Kritisch|Hoch|Mittel|Info
- Status: Bestaetigt | Verdacht, bitte pruefen
- Betroffener Bereich: Pfad oder Modul
- Was wurde gefunden?
- Warum ist das ein Risiko?
- Was koennte im schlimmsten Fall passieren?
- Wie dringend ist das?
- Was sollte als Naechstes geprueft oder behoben werden?
- Technik-Hinweis fuer Entwickler: optional, kurz

Good outcomes

A strong result from this agent:

• Lists only the most relevant risks for this repo
• Helps a non-technical stakeholder understand the business impact
• Gives developers enough location context to investigate quickly
• Stays strictly read-only