Contributing to Xila

Xila is the open-source core of a game security toolchain: the data model, the rule engine, the module host, and the CLI. Anything that runs on a developer's machine lives here under Apache 2.0.

The fastest useful contribution: a rule

Most detections are YAML data, not code. A rule that catches a real leaked key class in real game builds is worth more than a refactor.

1. Copy an existing rule from rules/secrets/ and edit it.
2. Add a fixture at rules/<pack>/testdata/<your-rule>.txt containing an obviously fake but format-valid value. Never commit a real credential, yours or anybody else's.
3. go test ./rules/... — the suite proves your rule matches its fixture and that no rule matches the clean corpus in rules/testdata/clean/.
4. Open a PR. Include where you have seen this key class shipped (a storefront build, an engine forum thread, vendor documentation) so a reviewer can judge the precision.

Read docs/writing-a-rule.md first. The bar for a merged rule:

• Precise. A false positive costs a developer's trust; a missed low-value key costs little. High-entropy generic patterns need an entropy gate and allowlist.stopwords.
• Actionable. remediation tells a game developer what to do in their own words: rotate where, move what to the server.
• Sourced. At least one references URL: vendor docs for the key format, or the advisory that makes it matter.
• Regexes are RE2. No backreferences, no lookaround. A rule must not be able to hang a scan on a hostile file.

A module

Modules are extractors, analyzers, probers, detectors and reporters. Built-in modules implement the Go interfaces in core/module; external modules speak JSON-RPC over stdin/stdout and can be written in any language (docs/module-protocol.md).

Write a new extractor when Xila should understand a new engine, packaging or platform. Every existing rule and analyzer then works on it immediately — that is the point of the architecture, so keep engine knowledge inside your extractor and never branch on engine in an analyzer.

Requirements for a built-in module PR:

• A manifest with honest Permissions. Xila is offline; a module that needs the network will not run without --allow-network, so needing it is a design decision, not a detail.
• Defensive parsing. You are parsing files an attacker controls: validate every offset and length against the real file size, cap every allocation and recursion depth, and return partial results plus an error instead of panicking. PRs adding a container format need a malformed-input test table.
• Tests with fixtures you generate in code, not downloaded samples. Never commit engine runtime binaries or game assets — they are not ours to redistribute.
• Deterministic output: same input, same components, same order.

Community modules are welcome as external modules; they are labelled as community in xila modules list and are not officially supported.

Development

go build ./cli/xila      # build the binary
go test ./...                # everything
go test ./rules/...          # rule fixtures and clean corpus
gofmt -l .                   # must print nothing
go vet ./...

Go 1.26, no code generation, no vendored dependencies. New third-party dependencies need a reason in the PR description and a permissive licence (Apache-2.0, MIT, BSD, ISC). GPL/AGPL code cannot be included, and neither can rule text copied from a GPL project.

Conventions

• Error messages name what failed and what to do; they end up in a developer's CI log.
• No secret value ever reaches a report, a log line or an error message. Build evidence with xila.MatchEvidence and let the core redact.
• Comments explain why, not what. Assume a reader who knows Go and does not know this codebase.
• Commit messages: imperative subject, one logical change.

Reporting things

• A vulnerability in Xila, or a leaked secret you found in someone else's game: SECURITY.md. Do not open an issue.
• A false positive: use the false-positive issue template and attach a redacted fixture; a fix usually means an allowlist entry plus a test.