59 lines
2.3 KiB
Markdown
59 lines
2.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
1. Open or select an issue that describes the research question or defect.
|
|
2. Create a focused branch from `main`.
|
|
3. Add implementation, positive tests, negative tests, and documentation.
|
|
4. Run the full unit-test suite and a scan of `examples/`.
|
|
5. Open a pull request using the repository template.
|
|
6. 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`](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.
|
|
|
|
```bash
|
|
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.
|