Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
127 lines (90 loc) · 4.11 KB

CONTRIBUTING.md

File metadata and controls

127 lines (90 loc) · 4.11 KB
Raw

Contributing to SecGraph-AI

Thank you for your interest in contributing. SecGraph-AI is a local-first AI security consultant built on Neo4j and Ollama. Contributions that improve reliability, extend the knowledge graph, add new analysis capabilities, or improve the user experience are welcome.

Before you start

Please open an issue before writing code. This avoids wasted effort if a feature is already in progress, outside scope, or planned differently. For bug fixes, an issue also helps confirm the bug is reproducible and understood before a fix is attempted.

Label your issue appropriately:

  • bug — something is broken
  • enhancement — new feature or improvement
  • good first issue — suitable for new contributors
  • help wanted — contributions actively sought
  • question — general question about the project

Development setup

git clone https://github.com/marjatmm-sec/SecGraph-AI.git
cd SecGraph-AI

# Copy and configure environment
cp .env.example .env
# Edit .env — set NEO4J_PASSWORD, NEO4J_DATA_DIR at minimum

# Start Neo4j
docker compose up -d

# Install dependencies
pip install -r requirements.txt

# Run ingestion (first time)
python src/ingestion/schema_setup.py
python src/ingestion/nist_loader.py
python src/ingestion/framework_loader.py --all

# Load sample data for testing
python src/ingestion/client_assessment.py \
  --client "FinServ Demo" \
  --csv sample_data/financial_services_client.csv \
  --frameworks "NIST 800-53 Rev 5" "PCI-DSS 4.0" "ISO 27001:2022"

# Launch the app
streamlit run src/ui/app.py

Branch naming

feature/short-description     ← new functionality
fix/short-description         ← bug fixes
docs/short-description        ← documentation only
refactor/short-description    ← code changes with no behaviour change

Always branch from dev, not master:

git checkout dev
git pull
git checkout -b feature/your-feature-name

Code standards

  • Python 3.11+
  • PEP 8 style — keep lines under 100 characters where practical
  • No hardcoded credentials or paths — use config.py and .env for all configuration
  • No client data — never commit anything from client_data/, exports/, or reports/
  • No pycache — clear __pycache__ before committing (find src -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null)
  • Syntax check before PR — run python -c "import ast; ast.parse(open('src/ui/app.py').read())" on any modified Python file
  • Update the README if you add a new file, tab, ingestion script, or change behaviour

Pull request checklist

When opening a PR, confirm the following:

  • Branched from dev, not master
  • No hardcoded credentials, IPs, or file paths
  • No client data committed
  • All modified Python files pass syntax check
  • Tested against at least one sample client (FinServ Demo or MultiCloud Corp)
  • README updated if behaviour or project structure changed
  • PR description explains what changed and why

What we will and won't merge

Will merge:

  • Bug fixes with a clear reproduction case
  • New ingestion parsers (vuln scanners, OSINT sources, frameworks)
  • New analysis modules consistent with the graph schema
  • UI improvements that don't break existing tabs
  • Documentation improvements
  • Performance improvements for large environments

Won't merge:

  • Features that require cloud APIs or send data off the local machine
  • Changes that break the local/portable nature of the project
  • PRs that commit .env, client_data/, or any real engagement data
  • Features without a clear security use case
  • Breaking changes to the Neo4j schema without a migration path

The maintainer reserves the right to decline PRs that don't fit the project direction, even if technically correct.

Reporting security vulnerabilities

Please do not open a public issue for security vulnerabilities in SecGraph-AI itself. See SECURITY.md for the responsible disclosure process.

Licence

By contributing to SecGraph-AI, you agree that your contributions will be licensed under the Apache License 2.0.