CONTRIBUTING.md

Contributing to Lumi Eggcracker

Lumi Eggcracker is a destructive, privileged Linux public alpha. Contributions are welcome, but a convenient detector or passing fixture is not enough to make new containment claims.

Choose the right route

• Use Q&A for questions and observed feedback from an actual supported-path run.
• Use the bug form for reproducible, non-security defects.
• Use private vulnerability reporting for an approval bypass, containment escape, false successful receipt, privilege issue, unsafe installer behaviour or other security-sensitive finding. Do not publish exploit details first.

Keep public Q&A to questions and observed feedback from an actual supported-path run. Coordinate any large code change through separately authorised maintainer review; do not use public support routes for product-direction proposals.

Local checks

Use Python 3.11 or newer. The ordinary unit suite does not grant permission to run native root or containment tests on your workstation.

python -m pip install jsonschema==4.26.0 ruff==0.16.1 PyYAML==6.0.3
ruff check src tests scripts
PYTHONPATH=src python -m unittest discover -s tests -v

For packaging changes, also build and verify the release material:

python scripts/build_release.py --output dist/github
python scripts/verify_release.py \
  --artifact dist/github/lumi-eggcracker-0.5.0.pyz \
  --source-archive dist/github/lumi-eggcracker-0.5.0-source.zip \
  --release-bundle dist/github/lumi-eggcracker-0.5.0-linux.zip

Any detector, profile, approval, installer, watchdog, containment or receipt change also requires the exact native gates in QUALIFICATION.md on a disposable supported Linux environment whose loss is acceptable. A Windows pass or GitHub Actions run cannot substitute for native qualification.

Product and evidence boundaries

Direct cgroup.kill plus exact empty proof remains authoritative. Do not add or claim unsupported backends, universal AI recognition, behavioural detection, network or credential isolation, malware prevention, EDR functions, or container/cloud coverage without a separately qualified release boundary.

Keep fixtures synthetic and reports redacted. Never commit credentials, private model data, machine-specific paths, raw process arguments or environments. Preserve existing package, CLI, service, socket, policy, receipt, schema and release identifiers unless a reviewed compatibility plan says otherwise.

Pull requests

Keep each pull request focused. State the exact user-visible change, tests run, platform and Python version, relevant skips, destructive-test boundary, and any documentation or compatibility impact. New behaviour needs positive, negative and failure-path tests. By submitting a contribution, you agree that it is provided under this repository's Apache-2.0 licence.