Service Research Journal

The service journal is a structured, revisioned living document attached to each service. It's the canonical source of truth — what the service is, how it works, and practical tips for other agents. Every edit creates a new revision, preserving the full history.

Sections

Section	What belongs here	What does NOT belong
overview	Business purpose, who uses it, what it does, target audience, industry	Technical stack details (use architecture)
architecture	Tech stack, frameworks, infrastructure, API patterns, deployment model, database type	How to access the service (use access)
access	URLs, auth methods, credential references (auth session IDs), ports, login flows, VPN requirements	Implementation details (use architecture)
surface_highlights	Key endpoints worth noting, important flows, unusual patterns, GraphQL schema, admin panels	Full endpoint inventory (tracked as separate entities — only the noteworthy ones here)
tips	WAF bypasses, rate limit behavior, captcha notes, practical tricks, curl shortcuts, session quirks	Vulnerability details (use known_issues)
known_issues	Confirmed vulnerabilities, protection gaps, misconfigurations, with references to assessment/finding IDs	Tips and bypass tricks (use tips)

Entity Reference Format

When referencing KB entities in journal content, ALWAYS use the entity_type://id format:

• endpoint://42 — the UI renders this as a clickable link to endpoint #42
• finding://7 — links to finding #7
• assessment://15 — links to assessment #15
• flow://3 — links to flow #3
• service://9 — links to another service

Other agents can parse these references to look up the mentioned entities.

Do: "The admin export endpoint (endpoint://42) accepts arbitrary SQL in the query parameter" Don't: "Endpoint #42 accepts arbitrary SQL" (not parseable by UI or agents)

Writing Style

• Be terse and factual. Write short, dense notes — not prose. Other agents need to scan this quickly.
• One finding per line. Use line breaks between distinct observations. Don't write paragraphs.
• Lead with the what, then the so-what. "Debug mode enabled on /api/debug — leaks stack traces with DB credentials" not "We discovered that the debug mode is enabled..."
• Include evidence. "Server: nginx/1.18.0 (from response header)" not just "Uses nginx".
• Reference entities. Always link to the endpoint, finding, or assessment ID when one exists.

Modes

The tool supports two modes:

• mode="append" (default) — adds your content at the end of the section. Use for adding new findings.
• mode="replace" — replaces the ENTIRE section content. Use when:
  • Correcting wrong information ("previously said nginx 1.18, actually 1.20")
  • Removing stale content ("debug endpoint was patched, no longer accessible")
  • Rewriting a messy section after too many appends
  • When using replace, you MUST include ALL content you want to keep — not just the new part

Every edit (append or replace) creates a new revision. Nothing is ever lost — the old content is always available in the revision history.

Rules

1. Read before write — always fetch the current journal first. Don't duplicate existing content.
2. Default to append — use mode="append" for new findings. Only use mode="replace" when correcting, removing, or rewriting.
3. Use entity references — always entity_type://id format for KB entities.
4. Right section — put content in the correct section. If unsure, refer to the section table above. Tips are for bypass techniques; known_issues are for vulnerabilities.
5. Revision summary is mandatory — must describe what changed, ≥10 chars. Be specific: "Added WAF bypass tip" not "Updated journal". For replace mode: "Corrected nginx version from 1.18 to 1.20" or "Removed stale debug endpoint entry".
6. No speculation — only document what you've observed or verified. "Server returns Django debug page" is fact. "Server might be vulnerable to X" is speculation (create an assessment instead).

Deduplication

Before appending, check if the journal already contains the same information:

• If the exact finding is already there → skip, don't duplicate
• If related info exists but yours adds detail → append the new detail only
• If existing info is contradicted by your finding → append your finding and note the contradiction: "Previously noted X, but testing shows Y instead"

Good vs Bad Examples

Good overview: "Main customer portal for ExampleCorp. Handles user registration, subscription management, and billing. B2C SaaS with ~50K users." Bad overview: "React 18 SPA with Next.js" (this is architecture, not overview)

Good architecture: "React 18 SPA with Next.js SSR. API at /api/v2/ backed by Express.js 4.18 (Server header). PostgreSQL database (leaked in error trace). Cloudflare WAF (CF-Ray header). Stripe integration for payments." Bad architecture: "Modern web application" (too vague, no evidence)

Good access: "Primary URL: https://app.example.com. Auth via JWT stored in httpOnly cookie 'session'. Login at /login with email+password. See auth session #3 for test credentials. Admin panel at /admin requires role=admin (cookie claim)." Bad access: "You can log in at the website" (no actionable detail)

Good tips: "WAF blocks standard SQLi but accepts Unicode-encoded variants. CAPTCHA on login is client-side only — bypass by omitting captcha_token parameter. Rate limiting resets every 60s per IP." Bad tips: "JWT secret is weak" (this is a known_issue, not a tip)

Good known_issues: "Debug mode enabled on /api/debug — returns full stack traces with DB credentials (assessment://45). JWT secret is weak — crackable with hashcat in <1min (finding://12). CORS allows *.example.com (assessment://67)." Bad known_issues: "To bypass WAF, curl directly to origin IP" (this is a tip, not an issue)

Good surface_highlights: "GraphQL introspection enabled at /graphql (endpoint://12) — full schema available. Password reset flow (flow://3) has no rate limiting. The /admin/export endpoint accepts raw SQL in the query parameter (assessment://45)." Bad surface_highlights: A list of every endpoint found (use the endpoint entities for that)