Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

README.adoc

Sanctify-PHP Documentation

Table of Contents

Overview

Welcome to the Sanctify-PHP documentation. This comprehensive guide covers everything from basic usage to advanced development.

Sanctify-PHP is a security analysis and hardening tool for PHP applications, with specialized support for WordPress. Built in Haskell, it provides:

  • Deep security analysis (OWASP Top 10 + advanced threats)

  • WordPress-native understanding

  • Automatic code transformations

  • Modern PHP 8.2+ parser

  • Multiple output formats

Documentation Structure

For Users

Quick Start Guide

Get up and running in minutes:

  • Installation methods (Cabal, Stack, Nix, binaries)

  • Basic usage examples

  • Common workflows

  • Configuration basics

User Guide - Part 1

Comprehensive user documentation:

  • Installation and setup

  • Command reference (analyze, fix, report, export)

  • Configuration file format

  • Vulnerability reference (SQL injection, XSS, CSRF, etc.)

User Guide - Part 2

Advanced features:

  • Advanced vulnerability detection (ReDoS, SSRF, XXE, TOCTOU)

  • WordPress-specific features (nonces, capabilities, REST API)

  • Workflow examples (pre-commit hooks, CI/CD, watch mode)

  • Performance tuning

  • Troubleshooting

For Developers

Architecture Guide

Understanding the codebase:

  • Module structure

  • Core AST design

  • Parser implementation (Megaparsec)

  • Emit module (code generation)

  • Security analysis pipeline

  • Transformation system

  • Type inference engine

Extending Guide

Add your own features:

  • Adding custom security checks

  • Creating transformations

  • WordPress-specific checks

  • Custom output formats

  • Plugin architecture

  • Testing extensions

  • Contributing guidelines

API Reference

Complete API documentation:

  • Sanctify.AST - Core types

  • Sanctify.Parser - Parsing functions

  • Sanctify.Emit - Code generation

  • Sanctify.Analysis.Security - Vulnerability detection

  • Sanctify.Analysis.Advanced - Advanced checks

  • Sanctify.WordPress.Security - WordPress checks

  • Sanctify.Transform - Code transformations

Quick Navigation

By Task

I want to…​

By Role

Security Auditor: * Quick Start - Get running fast * Vulnerability Reference - Understand what’s detected * WordPress Features - WP-specific checks

PHP Developer: * Quick Start - Installation and basic usage * Command Reference - All CLI commands * Workflow Examples - Integration patterns

Haskell Developer: * Architecture - Codebase structure * Extending - Add features * API Reference - Function signatures

WordPress Developer: * Quick Start - Get started * WordPress Features - WP-specific functionality * WordPress Checks - Add custom WP checks

Feature Highlights

Security Analysis

  • OWASP Top 10: SQL injection, XSS, CSRF, command injection, path traversal

  • Advanced Threats: ReDoS, SSRF, XXE, TOCTOU, timing attacks, object injection

  • WordPress-Specific: Nonce verification, capability checks, AJAX/REST API security

  • Modern PHP: Full PHP 8.2+ support (readonly classes, DNF types, enums, attributes)

Code Transformations

  • Strict Types: Add declare(strict_types=1) automatically

  • Type Hints: Infer and add parameter/return type hints

  • Sanitization: Wrap input with sanitize_* functions

  • Escaping: Wrap output with esc_* functions

  • SQL Safety: Convert queries to use $wpdb→prepare()

  • Crypto Modernization: Replace weak functions (md5 → SHAKE3-256)

Developer Experience

  • Interactive Mode: Review each fix before applying

  • Watch Mode: Re-analyze on file changes

  • Multiple Formats: Text, JSON, SARIF, HTML output

  • Severity Filtering: Focus on critical/high issues

  • Type Filtering: Analyze specific vulnerability types

  • Diff Preview: See exact changes before applying

Infrastructure

  • php.ini Export: Hardened PHP configuration

  • nginx Export: Security headers and settings

  • Guix Export: Reproducible package definitions

  • CI/CD Integration: SARIF format for GitHub/GitLab

Examples

Basic Analysis

# Analyze a file sanctify analyze index.php # Analyze with specific severity sanctify analyze src/ --severity=critical,high # Watch mode for development sanctify analyze src/ --watch

Interactive Fixing

# Review and apply fixes sanctify fix index.php --interactive # Preview changes without modifying sanctify fix index.php --diff

WordPress Plugin Audit

# Generate HTML audit report sanctify analyze wp-content/plugins/my-plugin/ \ --format=html > audit.html # Export hardened php.ini sanctify export-php-ini wp-content/plugins/my-plugin/ \ > php.ini.hardened

License

Sanctify-PHP is licensed under the PMPL-1.0-or-later license.

See LICENSE for details.

Support

Contributing

We welcome contributions! See Extending Guide for:

  • Adding custom security checks

  • Creating transformations

  • Writing tests

  • Submitting pull requests

Changelog

See CHANGELOG for version history and release notes.