CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Repository Overview
PiraGo Security News (security-news.pirago.vn) is an internal security intelligence and reporting website for PiraGo engineering teams and project managers. It hosts monthly vulnerability digests, major incident reports, and emergency response runbooks.
Architecture & Technology Stack
- Platform: Static website hosted on GitHub Pages with native Jekyll processing (
_config.yml,CNAME). - No Local Build Step: The site relies purely on GitHub Pages’ built-in Jekyll compiler. No local build tooling, npm packages, or Gemfile are required to generate the site.
- Layout System:
_layouts/default.html: Master layout providing HTML structure, SEO/meta tags, Google Tag, typography (Plus Jakarta Sans, JetBrains Mono), breadcrumbs, and dark/light mode toggle._includes/: Reusable partials (header.html,footer.html,google-tag.html).assets/: Global stylesheet (assets/css/pirago-theme.css), script (assets/js/pirago.jshandling dark mode, mobile menu, and real-time table filtering), and logos/icons.
- Content Organization:
index.html: Portal homepage listing latest critical incidents, recent monthly reports, and links to runbooks._data/monthly/YYYY-mm.yml: Bilingual (vi + ja) content of each monthly report; the single source of truth.monthly/andmonthly/ja/: Thin stubs (YYYY-mm.html) that only setmonthly: "YYYY-mm"and include_includes/monthly-report.html._data/i18n.yml: UI strings per language (vi,ja);ja/pages getlang: javia_config.ymldefaults.featured/<case>/(vi) andfeatured/<case>/ja/(ja, with explicitlang: jaandpermalink: /ja/featured/<case>/...so the URL keeps the/ja/prefix the layout relies on): Featured cases (major incidents, vulnerability analyses, runbooks), listed in_data/featured.yml(drives the homepage section, header dropdown and footer):gmo/: Incident reports for major external security crises (e.g.,gmo_onamae_security_incident_report.html).linux-cve-2026-98432/: Linux kernel TCP UAF analysis.php-cve-2026-109618-109619/: Single-page HTML runbook (PHP2Shell) for incident response and patching.
_templates/monthly-data.yml&_templates/monthly-stub.html/monthly-stub-ja.html: Templates for new monthly reports.monthly/RULES.md: Authoritative specification for monthly report structure and workflow.
Report Authoring & Publishing Workflow
When creating or modifying security reports, strictly follow monthly/RULES.md:
- Create New Monthly Report (3 files):
_data/monthly/YYYY-mm.yml: copy from_templates/monthly-data.yml, fill in every text field in bothviandja.monthly/YYYY-mm.html: copy from_templates/monthly-stub.html(keepsredirect_from).monthly/ja/YYYY-mm.html: copy from_templates/monthly-stub-ja.html(setslang: jaandpermalink: /ja/monthly/YYYY-mm/).
- Table & Content Standards:
- Tables are generated by the include from
sections(type: actions | component | provider | list); column labels, the#tableFilterInputfilter bar and severity badges (crit|high|med|low, labels from_data/i18n.yml) are rendered automatically. - Core technology focus areas:
- Infrastructure: AWS, GCP
- Languages & Runtimes: NodeJS, PHP, Java, .NET, JavaScript
- Frameworks: Next.js, Nuxt, Quasar, Laravel, Spring Boot
- Browsers & Package Registries: Chrome/V8, npm, Composer, Maven
- Tables are generated by the include from
- Cross-File Synchronization: none needed by hand. The header dropdown, footer links and the summary cards on
index.html/ja/index.htmlloop oversite.data.monthly(newest first, newest gets the “new” badge). Fill thecardblock in the data file for the homepage summary.
Fetching Public Sources
If a fetch of a public page returns HTTP 403 Forbidden or requires browser rendering, use an available Playwright or Chrome DevTools tool to open the URL and extract the rendered content. Discover and activate the browser tool if available; if neither is available, use another accessible public source.
Verify that the output contains the expected content, not an error, login, or challenge page. If access is still blocked or requires authentication, use another public source rather than trying to bypass the restriction.
Deployment & Common Commands
- Check Working Tree:
git status git diff - Deploy:
Commit changes and push directly to the
mainbranch. GitHub Pages automatically compiles Jekyll and deploys tosecurity-news.pirago.vn:git add <changed-files> git commit -m "add monthly security report YYYY-mm" git push origin main
Featured Case Pages (vulnerability analyses)
Every new vulnerability analysis page (featured/<case>/analysis.html + ja/analysis.html) must include, like the existing pages (e.g. featured/nginx-cve-2026-123007/):
- Diagrams / illustrations: hand-written inline
<svg>inside<figure class="fig">…<figcaption>(viewBox width 740,role="img"+aria-label). Use theme tokens only (var(--crit|high|med|low|text-muted|line|bg-subtle),fill="currentColor", classesbox/mut) so light and dark mode both work; give each arrow marker a uniqueidper page. Include the.fig*CSS in the page<style>(copy from the nginx page). Minimum set: (1) attack chain, (2) mechanism illustration when meaningful (e.g. buffer overflow), (3) affected/fixed version scope, (4) quick decision tree / remediation flow. Translate labels in the ja page; never show exploit detail. - SNS (OG) image:
featured/<case>/<name>-og.png, 1200x630, referenced byimage:in the front matter of both vi and ja pages. Render from a small HTML (dark navy gradient, JetBrains Mono, severity badge, name, CVE/GHSA id, one-line summary, affected → fixed versions,assets/images/logo_footer.webp,security-news.pirago.vn) with headless Chrome:"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless --hide-scrollbars --window-size=1200,630 --screenshot=<out.png> file://<html>. Keep the temp HTML in the scratchpad, not the repo. - Verify visually: screenshot the
<figure>blocks with headless Chrome and check for overlapping or clipped text before committing. - Register the case in
_data/featured.yml(vi + ja strings, includingmonth: "YYYY-MM"based on initial disclosure/occurrence month for/incidents/and/vulnerabilities/monthly archive pages). Sort order: entries in_data/featured.yml(bothincidentandvulnerability) must be ordered by initial public disclosure / occurrence date of the incident or vulnerability (newest first), not by article creation or last-updated date.
Rules
- Always “fan out subagents” to update the security news.
- Subagents for Search, Scan & Explore: Always use the Haiku model (
model: "haiku") when spawning subagents via theAgenttool for search, scan, codebase exploration, or research tasks (e.g.,Exploreorgeneral-purposesearch agents). - Featured sorting: Keep
_data/featured.ymlordered by initial disclosure/occurrence date (newest first) for both incidents and vulnerabilities.