GhostPatcher

GhostPatcher is a JSON-driven sequential patching engine designed to safely update applications. It processes configurations through three distinct phases—pre-flight validation, localized execution, and post -> patch -> verification to ensure precise file modifications and system integrity.

This document outlines the JSON configuration structure required for GhostPatcher. The engine operates in three sequential phases: validation, execution, and verification.

Root Structure

The configuration file requires a root object containing an array of patches.

{
    "version": 1,
    "patches": [
        {
            "id": "my-patch-v2",
            "app_name": "Miaw App",
            "desc": "Updates the app to version 2",
            "rules_desc": [],
            "default_installation_path": [
                "%programfiles%\\Miaw App", 
                "D:\\Games\\Miaw App"
            ],
            "app_signature_rules": [],
            "patch": []
        }
    ]
}

Patch Metadata

Every object within the patches array requires basic metadata to identify and describe the specific update.

Property	Type	Description
id	String	A unique identifier for the patch configuration (e.g., patch-cybercore-v2).
app_name	String	The name of the target application being patched.
desc	String	A concise description detailing the purpose or changes introduced by the patch.
rules_desc	String (array)	Just like taxonomy String for User to see the Badge or Fast Info

---

Default Installation Path (default_installation_path)

Accepts an array of common installation directories to optimize application discovery.

• Supports environment variables (e.g., %programfiles%).
• This property is optional and can be defined as an empty array [].

Validation Rules (app_signature_rules)

Pre-execution validation rules. If any rule fails, the patch process is aborted.

Rule Type	Description	Required Properties
is_writable	Verifies file existence and absence of OS-level locks.	filename
filename	Verifies file existence.	filename, matchcase (boolean)
hash	Verifies file integrity. Supported algorithms: CRC32, MD5, SHA1.	filename, hash, algo
filesize	Verifies file size within a specified byte range.	max (integer), min (integer)
text_match	Searches a text file for a regular expression pattern.	filename, regex

---

Patching Actions (patch)

Sequential actions executed during the patch phase.

Global Optional Flags:

• "required": false (Default: true): Ignores execution errors for the specific action.

Action Type	Description	Required Properties	Optional Flags
backup	Defines files to back up for potential rollback. Must be the first step.	files (array)
taskkill	Kill process by name	filename	force: false
delay	Pauses execution for a specified duration (in milliseconds).	delay (integer)
mkdir	Creates a directory. Ignores if the directory exists.	dir
rmdir	Deletes a directory.	dir	force: false
overwrite	Downloads and overwrites a local file.	src, dest
copy	Copies a file locally.	src, dest
rename	Renames or moves a local file.	src, dest
delete	Deletes a local file.	filename	force: false
create_new	Downloads a new file. Fails if the file exists locally.	src, dest
append	Downloads and appends text to a local file.	src, dest
replace_text	Replaces specific strings within a local file.	dest, search, replace
execute	Executes a local binary.	executable, args	admin: false, wait: false

---

Verification (check)

Post-execution validation. Utilizes the same rule schema as app_signature_rules.

If verification fails, the engine automatically triggers a rollback restoring the files defined in the backup action (if backup exist).

{
    "type": "check", 
    "checks": [
        {"type": "hash", "filename": "miaw.exe", "hash": "ac1091ea", "algo": "CRC32"}
    ]
}

Configuration Example

 {
    "version": 1,
    "patches": [
        {
            "id": "patch-cybercore-v2",
            "app_name": "CyberCore Server",
            "desc": "Upgrades core engine to v2.0, migrates local database, and updates configuration.",
            "rules_desc": [
                "Requires core.exe v1.5",
                "Must be in offline mode"
            ],
            "default_installation_path":[
                "%ProgramFiles(x86)%\\CyberCore",
                "%ProgramFiles%\\CyberCore"
            ],
            "app_signature_rules": [
                {"type": "is_writable", "filename": "core.exe"},
                {"type": "is_writable", "filename": "config/settings.ini"},
                {"type": "text_match", "filename": "config/settings.ini", "regex": "^offline_mode\\s*=\\s*true"},
                {"type": "filename", "filename": "core.exe", "matchcase": false},
                {"type": "hash", "filename": "core.exe", "hash": "a1b2c3d4", "algo": "CRC32"},
                {"type": "filesize", "filename": "core.exe", "max": 5000000, "min": 1000000}
            ],
            "patch": [
                {"type": "taskkill", "filename": "core.exe", "force":true},
                {"type": "backup", "files": ["core.exe", "config/settings.ini", "logs/update.log"]},
                {"type": "mkdir", "dir": "tmp_update"},
                {"type": "overwrite", "dest": "tmp_update/core.exe", "src": "repo/v2/core_patched.exe"},
                {"type": "copy", "dest": "core.exe", "src": "tmp_update/core.exe"},
                {"type": "overwrite", "dest": "db_migrator.exe", "src": "repo/tools/db_migrator.exe"},
                {"type": "execute", "args": "--upgrade-db", "executable": "db_migrator.exe","wait":true,"admin":true},
                {"type": "delay", "delay":1000},
                {"type": "delete", "filename": "db_migrator.exe", "force": true, "required": false},
                {"type": "rename", "src": "docs/readme_v1.md", "dest": "docs/readme_old.md"},
                {"type": "create_new", "dest": "docs/readme_v2.md", "src": "repo/v2/readme.md"},
                {"type": "append", "dest": "logs/update.log", "src": "repo/v2/changelog.txt", "required": false},
                {"type": "replace_text", "dest": "config/settings.ini", "search": "api_version=1", "replace": "api_version=2"},
                {"type": "check", "checks": [
                    {"type": "hash", "filename": "core.exe", "hash": "f9e8d7c6", "algo": "CRC32"}
                ]}, 
                {"type": "rmdir", "dir": "tmp_update", "force": true, "required": false}
            ]
        }
    ]
}