PolicyGraph-Lite

A lightweight policy analysis tool that transforms EPA Federal Register documents into queryable Neo4j knowledge graphs using natural language to Cypher conversion.

Status Badges

Build:
CI:
Security:
License:
Status:

Status

Phase 0 — repository bootstrap

Scope (MVP)

This repository targets EPA items from the Federal Register, implementing natural language to Cypher conversion over a small Neo4j graph. No vector database is included in the MVP scope.

What's in this repo now

• README.md
• LICENSE
• NOTICE
• .gitignore
• CODEOWNERS
• CONTRIBUTING.md
• .editorconfig

Security

PolicyGraph implements comprehensive security scanning and vulnerability management to ensure the highest standards of security and compliance.

Security Scanning Workflow

The project uses a multi-layered security approach with automated scanning on every commit, pull request, and weekly scheduled scans:

• Trivy Image Scanning: Container image vulnerability scanning with CVE database integration
• Trivy Filesystem Scanning: Codebase security analysis for configuration and secret detection
• pip-audit: Python dependency vulnerability scanning with Poetry integration
• Security Waiver System: Managed vulnerability acceptance with approval workflows
• Comprehensive Reporting: SARIF, JSON, and Markdown reports for GitHub Security tab integration

Security Tools

• Trivy: Container and filesystem security scanner
• pip-audit: Python dependency vulnerability scanner
• Bandit: Python security linter
• Safety: Python dependency security checker
• GitHub Security: Integrated vulnerability management

Security Configuration

• .trivy.yaml: Trivy scanner configuration with custom policies
• .trivyignore: Exclude patterns for false positives
• infra/security/waivers.yml: Security vulnerability waivers
• infra/security/security-config.yml: Security policies and thresholds

Running Security Scans

# Run comprehensive security scan (requires sec/trivy-pip-audit branch)
# This will be triggered automatically on the security branch

# Run specific scan types via GitHub Actions
# Navigate to Actions > Security Scan > Run workflow
# Select scan type: all, trivy-image, trivy-fs, pip-audit, or waiver-check

# View security reports
# Check the Actions tab for scan results and artifacts
# Review GitHub Security tab for vulnerability details

Security Waiver Management

Security waivers allow controlled acceptance of known vulnerabilities with proper documentation and approval:

1. Waiver Request: Document vulnerability details and business justification
2. Approval Process: Follow approval workflow based on severity level
3. Documentation: Include remediation plan and expiration date
4. Regular Review: Monthly review of active waivers
5. Expiration: Automatic expiration with renewal process

Security Compliance

• OWASP Top 10: Web application security standards
• NIST Cybersecurity Framework: Risk management framework
• ISO 27001: Information security management
• Zero-tolerance: Critical and high severity vulnerabilities

For detailed security information, see Security Documentation.

Getting Started

Prerequisites

• Python 3.9 or higher
• Poetry (Python dependency manager)
• Docker and Docker Compose (for Neo4j and services)

Installation

1. Install Poetry (if not already installed):

   curl -sSL https://install.python-poetry.org | python3 -

2. Clone the repository:

   git clone https://github.com/policygraph/policygraph.git
   cd policygraph

3. Set up Poetry and install dependencies:

   # Run the setup script (recommended)
   ./scripts/setup-poetry.sh
   
   # Or manually:
   poetry install --with dev
   cd docs && poetry install && cd ..

4. Start the development environment:

   make docker-up
   make quickstart

Development Commands

• make install - Install Python dependencies
• make install-dev - Install dependencies including development tools
• make test - Run tests
• make lint - Run linting checks
• make format - Format code
• make help - Show all available commands

Environment Configuration

The project uses three types of environment files to manage configuration and secrets securely:

Environment File Types

1. .env.example - Template file with all configuration options and example values

   • Status: Committed to version control
   • Purpose: Reference template for all environments
   • Content: All possible configuration keys with example/placeholder values

2. .env.local - Local development environment file

   • Status: Git-ignored (never committed)
   • Purpose: Developer's local environment configuration
   • Content: Actual values for local development

3. .env.production - Production environment template

   • Status: Committed to version control with commented keys only
   • Purpose: Production deployment reference template
   • Content: All keys commented out, no actual values

Setting Up Your Environment

1. Clone the repository (if not already done):

   git clone https://github.com/policygraph/policygraph.git
   cd policygraph

2. Create your local environment file:

   cp .env.example .env.local

3. Edit .env.local with your actual values:

   # Edit the file and replace placeholder values
   nano .env.local
   # or
   code .env.local

4. Verify .env.local is git-ignored:

   git status
   # .env.local should not appear in tracked files

Required Configuration

Essential for Development

• NEO4J_URI - Your local Neo4j instance
• NEO4J_USER - Neo4j username
• NEO4J_PASSWORD - Your Neo4j password
• DEBUG - Set to true for development
• LOG_LEVEL - Set to INFO or DEBUG

Optional for Development

• OPENAI_API_KEY - If using OpenAI services
• EPA_API_KEY - If testing EPA API integration
• SENTRY_DSN - If using Sentry for error tracking

Security Notes

• Never commit .env.local - It's automatically git-ignored
• Use strong, unique passwords - Don't reuse passwords from other projects
• Keep local secrets secure - Don't share your .env.local file
• For detailed guidance - See the Secrets Management Runbook

Architecture (high level, placeholder)

FastAPI backend with Neo4j integration and minimal React UI. Specific implementation details marked as TODO.

Contributing

See CONTRIBUTING.md for contribution guidelines.

License & Notices

See LICENSE and NOTICE files for licensing and attribution information.

Disclaimer

Not legal advice; verify against the Federal Register.

Security & Responsible Disclosure (placeholder)

For security vulnerabilities, please open a private channel or contact via email (placeholder).

Acknowledgments/References (placeholder)

• Federal Register API
• Regulations.gov API
• Neo4j documentation
• AutoGen documentation