Contributing

AAISA welcomes public research contributions through issues and pull requests. Contributions must preserve the project's defensive, local-first, evidence-first boundaries.

Development setup

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m unittest discover -s tests -v
python scripts/verify.py

No external dependency is required for the foundation. Discuss new runtime dependencies before adding them.

Contribution workflow

Open or select an issue that describes the research question or defect.
Create a focused branch from main.
Add implementation, positive tests, negative tests, and documentation.
Run the full unit-test suite and a scan of examples/.
Open a pull request using the repository template.
Address review comments and keep commits focused and attributable.

Rule proposal requirements

Every new rule must document:

threat or policy condition;
supported artifact classes;
deterministic detection logic;
evidence and redaction behavior;
severity rationale;
remediation guidance;
known false positives and evasion limits;
positive, negative, and ambiguous tests;
expected performance on large artifacts.

Rules must not execute scanned content, access the network, modify source files, or place full credential values in reports.

Detailed metadata, test, evidence, and reference requirements are defined in docs/RULE_AUTHORING.md.

Evaluation corpus changes

Corpus fixtures must be synthetic, nonfunctional, and safe to store publicly. Do not add live secrets, personal information, executable malware, or content that requires detonation. Each case must declare exact expected rule counts. Run the evaluator twice and confirm equivalent parsed results before proposing a corpus revision.

PYTHONPATH=src python -m aaisa evaluate research/corpus-v1/manifest.json

Commit guidance

Use a concise imperative subject, such as Add SPDX provenance rule. Keep unrelated changes separate. Reference the relevant issue in the pull request.

Review standard

Maintainers evaluate correctness, tests, safety invariants, research reproducibility, report compatibility, performance, and documentation. Security-sensitive changes may require a private review before public discussion.

2.3 KiB Raw Permalink Blame History