First Commit

CONTRIBUTING.en.md

@@ -0,0 +1,312 @@
+# Contributing
+
+[한국어](CONTRIBUTING.md) · English
+
+Thank you for your interest in the Korean edition of ARTEX (`artex-ko`). This document
+gathers the scope, policies, and procedures you should know before you start contributing.
+Before you send a contribution, please read [Authorized use and legal responsibility](#authorized-use-and-legal-responsibility)
+and [Localization policy](#localization-policy) first.
+
+- To report a bug or suggest a feature → use the [issue templates](https://github.com/jiwoochris/artex-ko/issues/new/choose).
+- If you find a translation or localization error → use the "translation/localization error" issue template.
+- If you find a security vulnerability → **do not open a public issue**; follow the procedure in [SECURITY.en.md](SECURITY.en.md).
+- Everyone who takes part must follow the [Code of Conduct (CODE_OF_CONDUCT.en.md)](CODE_OF_CONDUCT.en.md).
+
+---
+
+## Authorized use and legal responsibility
+
+ARTEX is an offensive-security tool in which an LLM multi-agent system performs penetration
+testing **autonomously**. Contributors are bound by the same scope limits as users.
+
+- When you verify code, run the tool only against **a target you own or have explicit written
+  authorization for**, or against a **locally isolated environment** (for example an
+  intentionally vulnerable target you own, such as OWASP Juice Shop or DVWA launched with Docker).
+- We do not accept code that scans, probes, or exploits real, production, or remote systems
+  outside the authorized scope, nor changes that encourage such use.
+- In the Republic of Korea, intruding into another party's information and communications
+  network without authorization, or causing a disruption to it, violates the Act on Promotion
+  of Information and Communications Network Utilization and Information Protection; and any
+  personal data collected or exposed falls under the Personal Information Protection Act. The
+  full notice is in the [README](README.en.md#️-read-first--authorized-use-and-legal-notice).
+
+Legal responsibility for how the code or documentation you contribute is used rests with the
+user who runs it. This repository is provided "AS IS."
+
+---
+
+## Localization policy
+
+The reason this repository exists is to **preserve the original
+[Autumn-27/ARTEX](https://github.com/Autumn-27/ARTEX)'s judgment performance exactly while
+changing only the user-facing output to Korean**. Translation contributions that depart from
+this policy can degrade performance, so we do not accept them.
+
+- **Do not translate the agent's internal reasoning prompts (the behavior-instruction body).**
+  The behavior benchmarked in the original language (Chinese) must be preserved. This body
+  lives in `agent/promptcatalog.go` and the DB seed (`agent_prompts`). Translating it causes
+  drift in the agent's judgment.
+- **Only user-facing output is forced into Korean.** This covers detection findings
+  (`report_finding`), fact summaries (`record_fact`), the final report, and chat responses.
+  The enforcement is a code-fixed tail called `langDirective()` in `agent/prompt.go`, appended
+  to the end of each role's system prompt. To change the output language, modify this function.
+- **Commands, payloads, code, URLs, and log text are not translated.** They are the originals
+  needed for analysis, so they are left as is.
+- **The original Chinese is preserved.** Documents keep the original in `README.zh.md` and UI
+  strings keep it in `web/messages/zh.json`, so that changes in the upstream repository are
+  easy to compare against. Korean translations are filled into `web/messages/ko.json`.
+- When you translate a new UI string, do not hard-code it; add it as a key in the message files.
+- **The output-language enforcement is a prompt nudge, not a hard cap.** `langDirective()`
+  **instructs** the model to output Korean; it does not force-lock the language. Korean fidelity
+  therefore varies with the model's capability, the role, and the context. Use a capable
+  (frontier-class) model when you verify localization changes. Cheap or small models can revert
+  reports and summaries to the original language (Chinese), so do not judge whether a translation
+  is applied correctly from a cheap model's output alone. The `max_tokens` pitfall when using
+  OpenAI-family models is covered in the
+  [README's "Model selection and output language" section](README.en.md#model-selection-and-output-language).
+- **The procedure for keeping up with upstream changes is in the maintainer document.** When
+  the original ARTEX is updated, the runbook for distinguishing preserved assets from
+  translation targets, reflecting them, and checking translation symmetry and drift is in
+  [MAINTAINING.en.md](MAINTAINING.en.md).
+
+---
+
+## Development environment
+
+This project consists of a **Go backend** (with the frontend embedded in a single binary) plus
+a **Next.js frontend**.
+
+The design intent of the main features is documented in the design docs under `docs/`. When you
+work on the feature that links vulnerabilities to traffic evidence (the report agent's automatic
+binding, `report_finding`'s `traffic_refs`, and so on), read the
+[vulnerability multi-traffic-evidence design doc](docs/finding-traffic-evidence-en.md) first.
+The original (Chinese) is preserved as `finding-traffic-evidence-zh.md` in the same folder.
+
+### Required versions
+
+- Go 1.26 or later (per `go.mod`)
+- Node.js 22 or later (per the release workflow)
+- Docker and Docker Compose (for local runs and verification)
+
+### Backend (Go)
+
+If Go is installed locally, run the following from the repository root.
+
+```bash
+go build ./...
+go vet ./agent/
+go test ./agent/
+```
+
+If you do not have Go locally, you can verify the same way with Docker. Keeping the module and
+build caches in named volumes makes re-runs faster.
+
+```bash
+docker run --rm -v "$PWD":/src -w /src \
+  -v artexko-gomod:/go/pkg/mod -v artexko-gocache:/root/.cache/go-build \
+  golang:1.26 sh -c 'go build ./... && go vet ./agent/ && go test ./agent/'
+```
+
+#### DB integration tests (postgres required)
+
+The `go test ./agent/` above **quietly skips the DB integration tests** that only run when
+connected to PostgreSQL. Six packages — `agent`, `config`, `db`, `evidence`, `llmrec`,
+`server` — contain tests that require a real database; if there is no `ARTEX_PG_DSN`
+environment variable and no `database` entry in the config file, those tests are skipped with
+`--- SKIP` and the package still ends in `ok`. As a result, if you fix one of these six
+packages and verify without a DSN, **it can pass locally (ok) while the PR's `go-db` job
+fails.**
+
+To run these tests locally, bring up PostgreSQL and pass `ARTEX_PG_DSN`. The example below
+launches the same `postgres:16-alpine` as CI on an isolated network, reusing the named volumes
+from above.
+
+```bash
+# 1) Bring up an isolated network and an empty postgres (same image and account as CI).
+docker network create artexko-db 2>/dev/null || true
+docker run -d --name artexko-pg --network artexko-db \
+  -e POSTGRES_USER=artex -e POSTGRES_PASSWORD=artex -e POSTGRES_DB=artex \
+  postgres:16-alpine
+until docker exec artexko-pg pg_isready -U artex -d artex >/dev/null 2>&1; do sleep 1; done
+
+# 2) Pass the DSN to run the DB integration packages (the DSN host is the container name).
+#    To run only the package you fixed, replace ./agent/ with config, db, evidence, llmrec, or server.
+docker run --rm --network artexko-db -v "$PWD":/src -w /src \
+  -v artexko-gomod:/go/pkg/mod -v artexko-gocache:/root/.cache/go-build \
+  -e ARTEX_PG_DSN='postgres://artex:artex@artexko-pg:5432/artex?sslmode=disable' \
+  golang:1.26 sh -c 'go test ./agent/ -count=1'
+
+# 3) Clean up.
+docker rm -f artexko-pg && docker network rm artexko-db
+```
+
+CI's `go-db` job **isolates each of these six packages with its own postgres** and forces them
+to run before merge (`.github/workflows/ci.yml`). If you changed a DB integration package, we
+recommend verifying that package directly with the method above before you open the PR.
+
+### Frontend (web)
+
+```bash
+cd web
+npm ci
+npm run dev          # dev server
+npm run build        # production build
+npm run build:static # static-export build (merge gate; includes TypeScript type checking)
+npm run check        # Biome lint/format check (informational; not a merge gate yet, due to pre-existing debt)
+npm run check:fix    # auto-fix
+```
+
+Formatting and linting before commit are managed with Biome. `lint-staged` automatically runs
+`biome check --write` on staged files.
+
+### Full run (Docker Compose)
+
+```bash
+cp .env.example .env     # set POSTGRES_PASSWORD
+docker compose up -d     # start artex + postgres → http://localhost:8787
+```
+
+---
+
+## Contribution process
+
+1. **Open an issue first.** For large changes it is better to align on direction via an issue
+   before you start. For small fixes (typos, links, obvious bugs) you can send a PR directly.
+2. **Fork** the repository and create a topic branch. Prefix the branch name with the nature of
+   the change, as in `feat/...`, `fix/...`, `docs/...`, `i18n/...`.
+3. Write the change and **run the relevant verification yourself.** For a Go change, make the
+   `build`/`vet`/`test` above pass. For a web change, make `npm run build:static` pass (it also
+   performs the merge gate and the TypeScript type checking). `npm run check` (Biome) still has
+   pre-existing lint debt inherited from upstream and is not a merge gate yet — `web.yml` runs it
+   only as an informational step — so you do not need to make all of it pass. Instead, just
+   confirm that **your change does not add new errors** (when you commit, `lint-staged`
+   automatically applies `biome check --write` to the files you staged). If you changed
+   documentation (`.md`), run `python3 -I scripts/check-doc-links.py` to confirm that in-repo
+   link/image references and document anchor (`#heading`) links are not broken. Anchors are built
+   from headings into slugs with the same rule as GitHub and matched, so if you change a heading's
+   text without also fixing the anchor links that pointed to it, it is caught here (CI's `docs`
+   workflow enforces the same check as a merge gate). This check is also wired as the `docs` hook in
+   the repository root's [`.pre-commit-config.yaml`](.pre-commit-config.yaml), so if you run
+   `pre-commit install` it runs automatically on every commit (it uses only the Python standard
+   library and no network, so it finishes without Docker).
+4. **Open a PR.** Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md) for the title and
+   description, and write what you changed, why, and how you verified it. If you changed the UI,
+   attach screenshots.
+5. For a user-facing change (feature, localization, documentation, detection rule, and so on),
+   add one line to the `[Unreleased]` section of the [changelog (CHANGELOG.en.md)](CHANGELOG.en.md).
+   Internal refactoring or test-only changes may be omitted.
+
+### Commit messages
+
+Follow the convention of the existing commit history. The format is `type(scope): description`,
+and the description is written in Korean.
+
+- `type`: `feat` · `fix` · `docs` · `chore` · `refactor` · `test` · `i18n`, and so on
+- `scope`: the changed area (`agent` · `web` · `server`, and so on); optional
+
+Examples.
+
+```
+feat(agent): 사용자 노출 출력을 한국어로 강제 (langDirective)
+docs: 한국어 README 작성, 원본은 README.zh.md 로 보존
+i18n(web): 대시보드 네비게이션 라벨 한국어 번역
+```
+
+---
+
+## Contributing detection rules and detection tests
+
+This repository also keeps, in [`detections/`](detections/), rules for **defending against and
+detecting** autonomous AI attacks like ARTEX. It consists of deployable [Sigma](https://sigmahq.io)
+rules ([`detections/sigma/`](detections/sigma/)), network [Suricata](https://suricata.io) rules
+([`detections/suricata/`](detections/suricata/)), a [MITRE ATT&CK](https://attack.mitre.org/)
+coverage layer ([`detections/attack/`](detections/attack/)), and tests that reproducibly prove
+these rules actually fire ([`detections/tests/`](detections/tests/)). When you add or change a
+detection rule, please honor the contract below. Seven test suites mechanically enforce much of
+this contract, so if you change only a rule and do not update the tests/layer, the tests fail.
+
+- **Ground every indicator in an observable fact.** The strings, User-Agents, and behavioral
+  thresholds a rule uses must be ones actually found in this repository's source, and must not be
+  inferred. State the source file that is the basis for the rule (for example, the `artex-enrich/1.0`
+  indicator is confirmed in `enrich/enrich.go`). The indicator-match tests
+  ([`detections/tests/indicators/`](detections/tests/indicators/)) check that each indicator is
+  still present in both the upstream source and the rule, so if an upstream resync changes a source
+  string, the test fails unless you fix the rule along with it. If you change the machine-readable
+  indicator list ([`detections/indicators/artex_indicators.csv`](detections/indicators/artex_indicators.csv)),
+  also update the MISP event that carries those same indicators
+  ([`detections/indicators/artex_indicators.misp.json`](detections/indicators/artex_indicators.misp.json)).
+  The MISP export test ([`detections/tests/misp/`](detections/tests/misp/)) enforces that the two
+  files match row by row and that the event is a valid MISP document loadable by pymisp.
+- **State limitations honestly.** Write what a rule cannot catch and its false-positive potential
+  in the Sigma rule's `description` and in the Suricata rule's comments. If something is a general
+  hunting lead (for example, a destructive command) rather than an ARTEX-specific signature, say so,
+  so that a single hit does not get used to conclude the attacker is ARTEX.
+- **Pass static validation.** A Sigma rule must pass the SigmaHQ validator criteria with zero issues
+  (`sigma check --validation-config detections/tests/sigma_lint/validators.yml`). Plain `sigma check`
+  runs only pySigma's core validators, so SigmaHQ conventions such as title casing, field/logsource
+  classification, and reference links are filtered only by this config. The four exceptions are
+  SigmaHQ monorepo conventions that do not fit a standalone rule set, and their rationale is recorded
+  in [`detections/tests/sigma_lint/validators.yml`](detections/tests/sigma_lint/validators.yml). A
+  Suricata rule must load cleanly with `suricata -T`.
+- **Ship a reproducible test with it.** Prove that the rule fires (or that its structure is valid)
+  with a test under [`detections/tests/`](detections/tests/). Generate the input deterministically
+  each time rather than committing binaries to the repository; assert properties that are independent
+  of the engine version (firing exists, no false positives) exactly; and for figures that fluctuate
+  with the version, assert a lower bound and record the baseline separately. If you add or change a
+  Sigma correlation rule, the backend portability test
+  ([`detections/tests/sigma_backends/`](detections/tests/sigma_backends/)) checks that the rule
+  converts across multiple backends, so keep it consistent with the backend-support description in
+  [`detections/README.md`](detections/README.md).
+- **Update the ATT&CK layer with it.** If you add or change an `attack.*` tag on a rule, update the
+  techniques and scores in [`detections/attack/artex_navigator_layer.json`](detections/attack/artex_navigator_layer.json)
+  to match. The consistency test enforces a bidirectional rule↔layer match, so it fails if there is a
+  rule tag missing from the layer or a layer technique missing from the rules.
+- **Do not include anything that reads as attack guidance.** The detection material in this repository
+  maintains a defense/detection posture only. We do not accept write-ups that aid an attack, such as
+  how to carry out an exploit or techniques for evading detection.
+
+The eight test suites run as-is with only Docker, and do not commit their artifacts to the repository.
+Each script exits with a non-zero code if any single assertion fails, so it can be dropped straight
+into CI or a pre-commit hook.
+
+```bash
+detections/tests/sigma/run.sh           # Sigma: sigma check + backend conversion + indicator preservation
+detections/tests/sigma_match/run.sh     # Sigma: atomic rules fire on malicious sample events, stay quiet on benign
+detections/tests/sigma_lint/run.sh      # Sigma: full SigmaHQ-convention validators + documented criteria
+detections/tests/sigma_backends/run.sh  # Sigma portability: does a correlation rule convert across backends
+detections/tests/suricata/run.sh        # Suricata: synthesize pcap → suricata -r → assert alert counts
+detections/tests/attack/run.sh          # ATT&CK: bidirectional layer ↔ rule consistency
+detections/tests/indicators/run.sh      # Indicators: rule's pinned indicators ↔ upstream source, both ways
+detections/tests/misp/run.sh            # MISP: indicator CSV ↔ MISP event sync + pymisp validity
+```
+
+To run all eight at once, use [`detections/tests/run-all.sh`](detections/tests/run-all.sh). It runs the
+eight sequentially in the same order as CI, runs the rest to the end even if an earlier suite fails, then
+prints a per-suite PASS/FAIL summary, and exits with a non-zero code if any one fails. An example of
+wiring this runner directly as a pre-commit hook is in the repository root's
+[`.pre-commit-config.yaml`](.pre-commit-config.yaml). If you install it with `pip install pre-commit &&
+pre-commit install`, the runner runs only on commits that change detection rules or the upstream source
+those rules pin (the same scope as CI), catching rule/test mismatches before push. The same config file
+also includes the `docs` hook that checks in-repo link/image/anchor references (the `check-doc-links.py`
+from step 3 of the contribution flow above).
+
+These eight tests are run by the repository CI
+([`.github/workflows/detections.yml`](.github/workflows/detections.yml)) on every push/PR that changes
+anything under `detections/`. The indicator-match test also runs when the upstream source files those
+indicators point to (`enrich/`, `selfupdate/`, `guard/`, `db/`, `cmd/artex/main.go`) change, catching the
+case where an upstream resync changes a User-Agent, marker, or default port and silently makes a rule
+stale. So a change that updates only a rule without updating the tests/layer, a rule that breaks a SigmaHQ
+convention, or a rule that is inconsistent with the source shows up red in CI before merge.
+
+The rule index and each rule's basis and limitations are in [`detections/README.md`](detections/README.md),
+and the tests' assertions and how to run them are in [`detections/tests/README.md`](detections/tests/README.md).
+
+---
+
+## License
+
+This project is distributed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. By
+submitting a contribution, you are taken to **agree that your contribution is also released under
+AGPL-3.0**. In particular, if you modify this project and provide it to users over a network (for
+example, as an online service), you must disclose the complete corresponding source code to those
+users. The full terms are in the [LICENSE](LICENSE) file.