www_archline_hu/AGENTS.md

AGENTS.md — machine-facing rules for this repo

Read this before touching anything. README.md explains the project to a human; this file states the rules an automated agent must follow. Where the two seem to disagree, this file wins for process questions.

---

1. What this repo is

It produces clean, deployable code baselines for the Cadline web sites hosted on tanis.cadline.hu. A baseline serves two purposes at once:

1. the known-good reference the HIDS baseline-diff compares the live docroot against;
2. the source of truth for deployment — the tree that will be pushed to the server, replacing direct editing on the live host.

The repo stores baseline constituents plus a generator, never the deployed tree. build-baseline.sh assembles out/ deterministically; out/ is git-ignored.

2. One site per branch

There is no per-site repo. Sites and CMS versions are separated by git branch:

Branch	Site	CMS core
main	www.archline.hu	Joomla 3.8.11
site/archlinexp.eu	www.archlinexp.eu	Joomla 3.9.2

build-baseline.sh is site-agnostic: it walks core/, packages/, deployed/, cadline/, overrides/ and contains no site-specific logic. A new site means a new branch with different content, not a modified script. If you find yourself editing the generator to special-case a site, stop — that is the wrong branch of the design.

Site branches are parallel and long-lived. They do not merge into main. Only repo-wide things (this file, README.md, the generator, lib/) belong on main.

3. The cardinal rule: never build a baseline from an infected tree

Every one of these sites is or was compromised. A baseline built by copying the live docroot would cement the malware into the reference and into every future deploy.

Therefore:

• Take the CMS core from the official upstream package, never from live.
• Take the site's own code from the developer source repo (git.cadline.hu/cadline/websource, per-site subdirectory), never from live.
• Only for extensions with no obtainable upstream may files come from live — and then they are vetted, not trusted.
• The build output must be double-checked before it is used. This is not optional: the archline baseline's first candidate contained 34 malware files, and only the double-check caught them.

4. Mandatory verification (do not skip, do not weaken)

After every build, run all of these against out/:

1. YARA with the operator's ruleset. Expected: zero hits.

2. IOC paths: not one entry of malware-iocs.paths may exist under out/.

3. Disguise sweep: no *.php.json, *.phar*, *.phtml*, _h3x_*; no .json file containing a PHP open tag.

4. Structural check — the rule that catches what content matching misses:

   An extra file on a CMS core component path that is not a template override (templates/<tpl>/html/...) is not a module. It is a leftover or a plant.

   Diff out/ against the vanilla package: for every path under a core component that the vanilla does not have, decide explicitly. This rule found a file-write webshell (components/com_mailto/mail.php) and an Akeeba Kickstart leftover carrying a password — both invisible to YARA.

5. Core version: assert the built libraries/src/Version.php is the intended release.

A contaminated baseline must never be shipped. If verification fails, fix the constituents and rebuild — do not filter the symptom out of out/.

5. Repository boundary (hard rule)

This repo lives on git.cadline.hu — the customer's Gitea, a different server from the operator's. Therefore:

• Never reference the operator's infrastructure here. No operator issue URLs, no operator hostnames, no Addresses-Issue: trailers pointing at operator trackers — not in files, not in commit messages, not in branch names.
• Issue tracking for this work lives on the operator side and is not linked from here. Describe what and why in the commit message itself instead.
• An @illusion.hu e-mail address in a commit trailer (authorship attribution) is the one accepted exception.

6. Commits and branches

• Conventional Commits, English, subject ≤72 chars, imperative mood.
• Trailer: Assisted-by: claude-code@<model> on AI-assisted commits.
• No Addresses-Issue: / Closes (see §5).
• Never force-push a branch someone else may be building on; on your own fresh branch it is fine (use --force-with-lease).
• Never push to main. Open a pull request; a human merges.
• Never commit a secret. These trees legitimately contain third-party code with embedded credentials — if you must refer to one, cite file:line and the type, never the value. Redaction applies to commit messages, docs and any output you produce.

7. Layer semantics (what goes where)

Directory	Holds	Source of truth
core/	CMS official package, deployed form, installer removed	upstream vendor
packages/<slug>/	extensions with obtainable upstream; modified ones authored as two commits (pristine → delta) so git diff documents our change	upstream + our patch
deployed/<slug>/	extensions with no obtainable upstream: vetted live files	live (vetted)
cadline/<slug>/	the site's own code	developer source repo
overrides/	the site's modifications to core files, on the current core's base	developer source
malware-iocs.paths	paths excluded from the build (droppers, leftovers)	this repo

overrides/ rsyncs last, so it wins over core/.

Do not take a customized core file from live. The updater skips customized files, so the live copy silently stays on an old base (the eu site ran a 3.9.2 version string over pre-3.8.13 com_users code). Take vanilla for the version you target, then apply only the genuine delta.

8. Definition of done

A baseline branch is done when:

• build-baseline.sh runs unmodified and produces out/;
• all five checks in §4 pass, and the numbers are recorded in the commit message;
• every layer's provenance is traceable (which file came from upstream, from the developer source, or vetted from live);
• no secret value appears anywhere in the diff or the message.