Socrates Blade

Security Testing Framework for Scriptlog PHP Blogware

What Is Socrates Blade?

Socrates Blade is a security scanner built for Scriptlog - a PHP blog platform. It checks your web application for common security flaws and gives you a clear report of what it finds.

Think of it as a health check for your website's security. It looks for weaknesses that attackers might try to exploit, so you can fix them before they become a problem.

What It Detects

Issue	What It Means
SQL Injection	Attackers could tamper with your database through input fields
Cross-Site Scripting (XSS)	Malicious scripts could be injected into your pages
Path Traversal	Unauthorized users might access files outside the web root
Server-Side Request Forgery (SSRF)	Your server could be tricked into making dangerous requests

And many more - the scanner tests against hundreds of attack patterns.

System Requirements

Requirement	Minimum Version	Why
Python	3.8+	Runs the scanner engine
PHP	7.4+	Extracts application routes from your Scriptlog installation
curl	Any recent version	Sends test requests to your site
OS	Linux, macOS, Windows (WSL)	Best results on Unix-like systems

To check your versions:

python3 --version
php --version

Installation

1. Download Socrates Blade

git clone https://github.com/scriptlog/socrates-blade.git
cd socrates-blade

2. Set Up a Virtual Environment

A virtual environment keeps Python dependencies organized and avoids conflicts with other projects.

python3 -m venv venv
source venv/bin/activate        # Linux / macOS
venv\Scripts\activate.bat       # Windows (CMD)
venv\Scripts\Activate.ps1       # Windows (PowerShell)

3. Install Dependencies

pip install -r scanrequirements.txt

4. Verify It Works

python3 socrates-blade.py --help

You should see a help message listing all available options.

Quick Start

Place Socrates Blade Inside Your Scriptlog Installation

For the smoothest experience, copy the tool into your Scriptlog directory:

cp -r socrates-blade /var/www/phpsite/public_html/
cd /var/www/phpsite/public_html/socrates-blade

When placed inside Scriptlog, the route extractor (export_routes.php) automatically finds your config.php and reads the correct application URL.

Standalone Installation

If you prefer to keep the scanner separate:

cp -r /your/scriptlog/lib /your/scanner/directory/socrates-blade/
cp /your/scriptlog/config.php /your/scanner/directory/socrates-blade/

Generate Application Routes

Routes tell the scanner what pages and endpoints to test.

php export_routes.php > routes.json

This produces a routes.json file containing:

Current timestamp
Application URL from config.php
All available routes in your Scriptlog installation (frontend, admin, API, and more)

Run Your First Scan

Make sure your web server is running, then:

./run-scan.sh http://localhost

The scanner will:

Confirm your URL is reachable
Check system requirements
Set up the Python environment
Run security tests against all discovered routes
Generate a results report

Try a Dry Run First

A dry run shows what the scan would do without actually sending any requests:

./run-scan.sh http://localhost --dry-run

This is useful for learning how the scanner works before running a real test.

Common Usage Examples

Basic Scan (No Authentication)

./run-scan.sh http://localhost

Scan with Authentication

Some areas of your site require login. Supply credentials to test those too:

./run-scan.sh http://localhost \
    -u admin \
    -p your_password \
    -o findings.json

Generate an HTML Report

./run-scan.sh http://localhost \
    -u admin \
    -p your_password \
    --html-report report.html

Aggressive Mode (Thorough Testing)

Aggressive mode runs deeper tests but takes longer:

./run-scan.sh http://localhost --aggressive --timeout 30

Route Scans Through a Proxy (e.g., Burp Suite)

./run-scan.sh http://localhost --proxy http://127.0.0.1:8080

Skip URL Validation

Use this if your target isn't directly reachable but you still want to scan:

./run-scan.sh http://localhost --no-validate

Understanding Scan Results

Severity Levels

Level	What It Means	When to Fix
CRITICAL	Immediate danger - data breach or full system compromise possible	Within 24 hours
HIGH	Serious vulnerability that can be exploited	Within 7 days
MEDIUM	Moderate risk - should be addressed	Within 30 days
LOW	Minor issue - fix when convenient	Within 90 days

Report Formats

Format	Command	Best For
JSON	`-o report.json`	Automation, CI/CD pipelines
HTML	`--html-report report.html`	Reading in a browser

Command-Line Options

Authentication

Flag	Description
`-u, --username <name>`	Your login username
`-p, --password <pass>`	Your login password

Scan Behavior

Flag	Description
`--aggressive`	Run more thorough tests (slower)
`--brute-force`	Test password guessing
`--threads <n>`	Number of parallel tests (default: 5)
`--timeout <seconds>`	Max wait time for responses (default: 5s)
`--proxy <url>`	Route traffic through a proxy
`--wordlist <file>`	Custom password list for brute force

Reports

Flag	Description
`-o, --output <file>`	Save JSON report to file
`--html-report <file>`	Save HTML report to file
`--report-dir <dir>`	Directory for report storage

Other

Flag	Description
`--no-sync`	Skip route synchronization
`--no-validate`	Skip URL reachability check
`--dry-run`	Preview actions without executing
`-v, --verbose`	Show detailed progress
`-h, --help`	Display help message

Running Tests

# URL validator tests
./tests/bash/test_url_validator.sh

# BATS test suite
bats tests/bash/run-scan.sh.test.bats

CI/CD Integration

Add security scanning to your GitHub Actions pipeline:

name: Security Scan
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: pip install -r scanrequirements.txt
      - name: Run security scan
        run: |
          ./run-scan.sh ${{ secrets.TARGET_URL }} \
            -u ${{ secrets.TARGET_USER }} \
            -p ${{ secrets.TARGET_PASS }} \
            -o scan-results.json \
            --html-report scan-report.html

Troubleshooting

"Python not found"

Install Python 3, then check:

python3 --version

"curl not found"

Install curl using your system's package manager (e.g., apt install curl, brew install curl).

"Permission denied"

Make the script executable:

chmod +x run-scan.sh

Scan Fails to Connect

Make sure your web server is running
Try --no-validate if the URL isn't reachable
Check firewall settings

Important Notes

Only Test Systems You Own - or Have Written Permission to Test

Running security tools against websites without authorization is illegal. Always:

Get written permission from the system owner before testing
Use the tool on your own development environment
Follow responsible disclosure practices if you find real vulnerabilities

Respect Rate Limits

Don't overwhelm the target server. Adjust --timeout and --threads to keep your testing reasonable.

Project Structure

socrates-blade/
├── socrates-blade.py       # Main scanner engine
├── run-scan.sh             # Automation wrapper (start here)
├── config.py               # Scanner configuration
├── routes.json             # Application routes extracted from Scriptlog
├── export_routes.php       # Route extractor for Scriptlog installations
├── scanrequirements.txt    # Python package dependencies
├── url-validator-lib.sh    # URL validation library sourced by run-scan.sh
├── payloads/               # Attack test payloads
│   ├── xss.txt            # 116 XSS test strings
│   ├── sqli.txt           # 150 SQL injection test strings
│   ├── traversal.txt      # 139 path traversal test strings
│   └── ssrf.txt           # 191 SSRF test strings
├── wordlists/              # Brute force wordlists
│   ├── passwords.txt      # 498 common passwords
│   └── usernames.txt      # 1916 common usernames
├── tests/
│   ├── bash/              # Shell script tests
│   └── python/unit/       # Python unit tests
├── reports/                # Generated scan reports
├── lib/                    # PHP library for route extraction
├── venv/                   # Python virtual environment
├── CODE_OF_CONDUCT.md     # Community guidelines
├── CONTRIBUTING.md        # Contribution guide
├── LICENSE.md             # MIT License
├── SECURITY.md            # Security policy
└── README.md              # This file

Route Coverage

The route extractor (export_routes.php) covers all Scriptlog endpoints:

Category	Routes	What It Tests
Frontend	12	Home, posts, categories, tags, archives, search, pages, privacy, downloads
Admin	75+	All admin pages (auth, content, users, media, settings, import/export, etc.)
API	45	Full REST API (posts, categories, comments, archives, search, GDPR, media)
Public	3	Comment submission, contact forms, subscriptions
Sensitive	6	Install wizard, configuration files

Total: 142 routes (up from ~62 in v1.0)

Getting Help

Issue Tracker - Report bugs or request features
Browse the source: socrates-blade.py and config.py
Review attack payloads in the payloads/ directory to understand what each test does

License

MIT License

Version: 3.2.0
Last Updated: April 2026
Maintained by: M.Noermoehammad

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets		assets
payloads		payloads
tests		tests
wordlists		wordlists
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
config.py		config.py
export_routes.php		export_routes.php
routes.json		routes.json
run-scan.sh		run-scan.sh
scanrequirements.txt		scanrequirements.txt
socrates-blade.py		socrates-blade.py
url-validator-lib.sh		url-validator-lib.sh

Uh oh!

Latest commit

History

Folders and files

Repository files navigation