Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
54 lines (36 loc) · 3.05 KB

CONTRIBUTING.md

File metadata and controls

54 lines (36 loc) · 3.05 KB
Raw

Contributing to Glasshaus

Thanks for your interest in helping build Glasshaus! This project aims to be the honest personal-exposure scanner — open, transparent, and self-audit-first. Contributions that uphold that spirit are very welcome.

Status: Glasshaus is pre-alpha. The design is captured but implementation is just beginning, so the most valuable contributions right now are connectors, design feedback, and documentation.

Ground rules

By participating you agree to:

  • Abide by our Code of Conduct.
  • Respect the project's purpose and limits in DISCLAIMER.md. Glasshaus is a self-audit tool. We will not accept contributions whose primary purpose is to target, surveil, or de-anonymize other people, or to evade platform terms in a way that harms others.
  • License your contributions under the project's MIT License.

Ways to contribute

  • New connectors — wrapping an OSINT tool or API as a Glasshaus connector. This is the highest-impact contribution.
  • Correlation & scoring — improving entity resolution, confidence, and the exposure score.
  • Remediation guidance — mapping exposure types to concrete, accurate advice.
  • Frontend / UX — the dossier card, the Explore-mode graph view.
  • Docs, tests, bug reports.

Connector contributions (the important bit)

Every connector, no matter what it wraps, must:

  1. Implement the common Connector interface and emit only normalized Finding records — never tool-native output.
  2. Declare its metadata honestly: accepts (selector types), cost, rate_limit, requires_key, intrusiveness, and tier (fast / deep).
  3. Tag each finding with the correct exposure_type so remediation mapping works.
  4. Attach provenance to every finding (source, queried selector, evidence reference).
  5. Respect rate limits and fail in isolation — a connector error must never abort a scan.
  6. Never require committing a real API key; keys are supplied by the operator at runtime.

A connector-authoring guide will live in docs/ once the connector framework lands. Until then, open a discussion/issue describing the tool you want to integrate.

Development workflow

The toolchain is still being set up; this section will be expanded as the codebase lands. Expected shape:

  1. Fork and branch from main (feature/<short-name> or connector/<tool-name>).
  2. Keep changes focused; one logical change per pull request.
  3. Add or update tests for behavior you change.
  4. Run the linters/formatters and the test suite before pushing.
  5. Open a pull request describing what changed and why, and link any related issue.

Commit & PR conventions

  • Write clear, imperative commit messages ("Add Holehe connector", not "added stuff").
  • Keep PRs reviewable; explain trade-offs in the description.
  • Be responsive to review feedback — we aim to be kind and constructive in return.

Questions

Open a GitHub issue or discussion. For anything security-sensitive, follow SECURITY.md instead of filing a public issue.