patchpivot - PatchPivot is a defensive variant-analysis workspa

项目说明

PatchPivot

PatchPivot is a defensi workspace for tracking security
patches, organizing reproducible research, and carrying findings through
responsible disclosure.

This repository is not an exploitation framework and is not a replacement for
human authorization, scoping, or disclosure review. It is a workbench for
defensi research: patch diffing, source review, binary
analysis, fuzzing harnesses, crash triage, mapping, and coordinated
reporting.

PatchPivot can be dri, by an MCP-aware research CLI such as a
proprietary Ink Security CLI, by erosolar --profile ,
or by any orchestrator that can read and write the in directories
described below.

Core Research Model

The workflow starts from a recently fixed or security-relevant
commit:

1. Identify the patch, ad, affected range, and bug class.
2. Compare and patched code to isolate the primitive that changed.
3. Search for related code paths where the same primitive may still exist.
4. Build minimal harnesses around the relevant parser, syscall, library, or
binary interface.
5. Fuzz and triage crashes inside an isolated lab.
6. Reduce e to a defensible proof of impact.
7. Report through HackerOne, Bugcrowd, PSIRT, CERT/CC, an internal
ad process, or another authorized coordinated disclosure channel.

PatchPi separates the durable research record from bulky,
en artifacts. The repository stores source notes, harness
code, minimized proof material, and disclosure records. Large binaries,
decompiler projects, raw fuzzing corpora, , crash dumps, and tool
caches should li the repo in an artifact store.

Repository Layout

An in directory normally contains:

Requirements

Minimum local requirements:

Git

Node.js 18 or newer for scripts/patch-watch.mjs

Bash, WSL, Git Bash, or another POSIX-compatible shell for

scripts/new-in.sh

Recommended research tooling:

Kali Linux with the kali-linux-e metapackage for a broad toolset

AFL++, libFuzzer, honggfuzz, or target-nati

GCC, Clang, sanitizer runtimes, CMake, Make, Ninja, and target build systems

GDB, LLDB, rr, strace, ltrace, perf, bpftrace, , and core dump tools

Ghidra with analyzeHeadless for repeatable decompilation pipelines

BinDiff, Diaphora, Semgrep, CodeQL, Joern, cscope, ctags, or tree-sitter tools

QEMU, Docker, Podman, systemd-nspawn, Firecracker, or cloud VMs for isolation

SDKs, symbols, debug packages, firmware images, or source

mirrors when authorized

This repository does not currently ship an MCP server, Kali image, Ghidra plugin,
or proprietary Ink Security CLI source. It defines a filesystem contract
that those tools can drive.

Quick Start

Create a manual in:

Populate intel/sources.md and README.md, then drive the in with
your preferred operator:

or, for an MCP-aware proprietary CLI:

The exact CLI name and flags depend on the private implementation. The important
contract is that the orchestrator treats the finding directory as the source of
truth and writes durable e back into the expected subdirectories.

Run the patch watcher:

Run one target only:

Limit fallback date range when no previous state exists:

The first run for each target seeds state/watch-state.json and queues nothing.
The second and later runs queue candidate in.

Proprietary CLI Integration Contract

If a proprietary Ink Security CLI is used to dri, treat the
CLI as an orchestration layer rather than a hidden database. The CLI may be
closed-source, but the research record it produces should remain inspectable in
this repository.

Recommended responsibilities:

read target and finding metadata from the workspace

start scoped MCP tool calls for Kali, source analysis, fuzzing, triage, and

headless Ghidra

write durable output files under the acti directory

register large artifacts by hash

maintain run logs with timestamps, commands, tool , and exit codes

enforce scope files and disclosure guardrails

refuse unsafe or out-of-scope execution by default

Recommended commands:

Recommended exit codes:

Recommended JSON-lines event stream:

Recommended proprietary-source boundary:

keep private CLI source in a separate private repository or signed package

commit only public integration contracts, schemas, and generated e here

record CLI , MCP ser, and policy bundle hash in each run log

ne API tokens, portal credentials, private exploit material, or

customer data

Suggested run-log location:

Suggested run-log minimum fields:

Watcher Internals

scripts/patch-watch.mjs is intentionally small and auditable.

Input:

targets.yaml

state/watch-state.json

command-line flags: --target, --since, --dry-run

Local cache:

.cache/mirrors/<target> stores bare Git mirrors

mirrors are created with git clone --bare --filter=blob:none

existing mirrors are updated with git fetch --filter=blob:none origin

State behavior:

if a target has no lastSha, the watcher records current HEAD and queues

zero in

if a target has lastSha, the watcher inspects lastSha..HEAD

after a non-dry run, lastSha ad to current HEAD

Candidate heuristic:

commit subject and body are scanned with a security-focused regular expression

terms include C, security fixes, hardening, memory-corruption

classes, sanitizer references, syzbot, race conditions, side channels, and
common o terminology

the heuristic intentionally prefers false positives o candidates

Queue output:

The queued intel/sources.md includes:

commit SHA

upstream repository URL

guessed commit view URL

commit subject

first 60 lines of commit body

ad feed

configured disclosure or bounty channel

The watcher is not a oracle. It is a triage feeder.

Target Configuration

Targets are declared in targets.yaml:

Fields:

name: short stable slug used for cache and finding names

product: human-readable product label

repo: upstream source repository URL

ad: ad feed, RSS feed, mailing list, or portal URL

bounty: disclosure program URL when one exists

notes: portfolio rationale and bug-class hints

Good targets usually have:

regular security patch

a bug class with potential

reachable source or binary distributions

testable historical

clear disclosure paths

authorization for the work being performed

Current checked-in targets include Linux kernel, Chromium/V8, OpenSSL, WebKit,
and glibc.

In Statuses

Use these statuses consistently in findings/<slug>/README.md:

Research Phases

1. Recon

Record:

CVE or ad identifier

ad URL

patch commit or release tag

affected

fixed

target component

bug class and CWE when known

reachable attack surface

disclosure program or PSIRT route

authorization notes

Output:

intel/sources.md

initial README.md hypothesis

2. Acquire

Collect only what is needed and legally permitted:

source checkout

patched source checkout

release tarballs

debug symbols

container image or

target binaries

test corpus

build scripts

exact compiler and dependency

Record SHA-256 hashes for binaries and large inputs. Keep hea out of
Git.

Suggested external artifact layout:

3. Diff

For source-a targets:

inspect patch hunks

identify changed functions and call sites

locate added bounds checks, lifetime changes, type checks, parser state

transitions, integer-size changes, or error-handling changes

compare and fixed control flow

write the exact primitive in plain language

For binary-only targets:

import and patched binaries into Ghidra or another RE tool

run headless analysis with identical settings

export function hashes, symbol tables, call graphs, strings, and decompiled

changed functions

compare function similarity with BinDiff, Diaphora, or a custom script

confirm changes against runtime traces when possible

Output:

diff/patch-analysis.txt

changed-function lists

call graph notes

decompiler snippets where useful

4. Search

Search for code that repeats the same unsafe assumption:

same helper API used without the new guard

same parser state machine in another file format

same backend implementation in a different platform layer

same compiler optimization in another IR node or tier

same syscall, ioctl, socket family, or protocol operation

same arithmetic pattern with different field names

same allocation/copy/free sequence in neighboring code

downstream forks missing the upstream patch

Record candidates in the table with status and rationale.

5. Harness

Harnesses should be minimal, reproducible, and scoped:

isolate the suspected parser or function

avoid network scanning or third-party systems

prefer local files, stdin, synthetic sockets, or test fixtures

build with sanitizers when a

pin compiler flags and target

produce deterministic output

Useful build modes:

Do not turn a proof into a weapon. The goal is to pro and impact
inside the authorized lab, not to add persistence, stealth, lateral mo,
credential access, or payload delivery.

6. Fuzz

For fuzzing:

start with patch-deri

keep raw fuzzer output outside the repo

minimize crashing inputs before committing

store sanitizer logs and reproduction commands

record corpus pro

separate suspected duplicates from unique root causes

Recommended external layout:

Commit only stable, minimal, disclosure-safe inputs under crashes/.

7. Triage

Correlate crash behavior with code:

sanitizer report

debugger backtrace

register and memory summary

crashing input hash

and patched reproduction result

exact commit or package

decompiler/source line mapping

exploitability assessment limited to impact classification

Output:

triage/*.txt

crashes/*.txt

updated README.md status and table

8. Disclosure

Every in must end in a coordinated channel:

HackerOne

Bugcrowd

PSIRT

CERT/CC

internal write-up

published ad after the applicable coordination period

disclosure.md should include:

summary

affected products and

fixed when known

class

impact

reproduction en

minimal proof material

analysis

remediation guidance

timeline

reporter and contact information

Update disclosures/log.md after submission.

MCP-Dri

MCP is useful as the control plane for repeatable research. PatchPi
MCP tools to operate on explicit finding directories and produce auditable files,
not hidden chat-only state.

Recommended MCP tool groups:

MCP safety controls:

require an explicit finding path for every tool call

require an explicit authorization scope file before lab execution

default network access to off unless the task requires fetching public source

block commands that target third-party IP ranges unless scope allows them

mount the repo read-write and large artifacts read-write in separate paths

record command, working directory, timestamp, exit code, and artifact hashes

redact secrets before writing logs

require human appro public disclosure or external submission

Example kali_lab.run request:

Example kali_lab.run response:

Example ghidra_headless.analyze request:

Example ghidra_headless.analyze response:

Example MCP en :

Expected MCP run record:

Kali Linux E as a Lab Backend

kali-linux-e is useful because it provides a broad security research
tool in in one en. In PatchPivot it should be used as an isolated
analysis backend, not as an unrestricted attack box.

Recommended setup:

Isolation recommendations:

use snapshots before each experiment

keep target networks host-only or private by default

disable shared clipboard and drag-drop for malware or exploit-chain research

mount source read-only when feasible

mount artifacts separately from the Git worktree

ne API tokens or disclosure portal credentials inside target VMs

log tool and package state with every run

Useful Kali package families:

reverse engineering: Ghidra, radare2, binutils, strings, objdump, readelf

debugging: gdb, lldb, strace, ltrace, rr where supported

fuzzing: afl++, honggfuzz, radamsa, zzuf, corpus tools

binary exploitation research: pwntools, checksec, ROPgadget for impact

classification in authorized labs

web/browser research: Chromium builds, WebKit dependencies, protocol tools

source analysis: semgrep, ctags, cscope, ripgrep, tree-sitter tools

systems research: qemu, debootstrap, chroots, kernel build dependencies

PatchPivot does not require Kali specifically. Ubuntu, Debian, Fedora, Nix,
Windows with WSL2, macOS, or cloud runners can drive the same finding structure
as long as the required tools are a.

Headless Ghidra on Any OS

Headless Ghidra is the preferred repeatable binary-analysis backend when source
is una or when the source patch must be correlated with shipped binaries.

Typical headless flow:

Recommended exports:

program metadata

import table

export table

strings

function list

function hashes

decompiled functions around the patch

call graph

xrefs to changed functions

data references to changed constants

p-code or decompiler AST for custom comparison

Suggested output location:

Headless Ghidra can run on:

Kali or Debian lab machines

Windows analyst workstations

macOS workstations

Linux cloud workers

CI runners

offline malware-analysis or A labs

For large targets, keep Ghidra projects outside Git and commit only exported
summaries.

Source-Code Analysis Expansion

PatchPi well with source-centric security tooling:

rg for fast literal and regex searches

tree-sitter queries for syntax-aware patterns

Semgrep for reusable bug-class rules

CodeQL for dataflow and control-flow queries

Joern for code property graphs

compiler warnings and sanitizers for build-time e

custom scripts that emit SARIF or JSON for repeatable findings

search examples:

When an MCP source-analysis tool produces results, store:

Each result should include:

repository URL

commit SHA

query or rule identifier

matched file and line

why it may be a

triage status

Cloud Deployment

Cloud is useful for bursty builds, large fuzzing jobs, and headless binary
analysis. Use ephemeral infrastructure and keep sensiti controlled.

Recommended pattern:

Worker requirements:

pinned image digest

no long-li

least-pri object storage access

egress restrictions

job-level logs

artifact manifest with SHA-256 hashes

automatic teardown

Good cloud jobs:

compile and patched targets

run headless Ghidra export

run sanitizer test suites

fuzz an already authorized harness

minimize crash corpora

generate source-query reports

Poor cloud jobs:

handling embargoed samples without encryption and access controls

running unre exploit chains

scanning public address space

storing disclosure portal credentials

uploading sensiti samples to public multi-scanners

Anti-Virus and Malware-Analysis Lab Use

Some research targets, crash samples, or generated binaries may trigger endpoint
security controls. Treat AV or EDR en as controlled labs.

Appropriate uses:

obser a proof binary, crash input, or parser sample is detected

that internal detections cover a parser path

compare telemetry between and patched

document defensi for a disclosure or internal ad

Controls:

use isolated VMs with snapshots

keep samples off shared dri explicitly approved

do not upload private samples or embargoed crash files to public

multi-scanner services

do not attempt A, e, persistence, or stealth

document engine , signatures, policy, and timestamp

destroy or archi according to lab policy

PatchPivot's AV-lab role is e collection for defense, not e.

Disclosure Guardrails

This project assumes authorized research only.

In scope:

source and binary diffing

local reproduction in owned or authorized en

fuzzing authorized targets

minimal proofs of reachability and impact

coordinated disclosure

defensi and remediation notes

Out of scope:

unauthorized scanning or exploitation

credential theft

persistence

stealth

lateral mo

destructi

public release before coordination is complete

brokering or silent retention of

Every finding must land in a disclosure terminal:

A finding is not closed until disclosure.md and disclosures/log.md reflect
the coordinated outcome.

Adding a New Target

1. Edit targets.yaml.
2. Add a unique name.
3. Add the upstream source repo when a.
4. Add the ad feed or portal.
5. Add bounty or PSIRT information.
6. Explain the target's value in notes.
7. Run the watcher in dry-run mode.
8. Run the watcher normally once to seed state.
9. Review queued candidates on later runs.

Example:

Adding a New Finding

Manual path:

Watcher path:

Then:

1. Update findings/<slug>/README.md.
2. Fill intel/sources.md.
3. Add intel/scope.md if an MCP or lab runner will execute tools.
4. Add diff e under diff/.
5. Add harness code under harness/.
6. Add minimized proof inputs and logs under crashes/.
7. Add debugger and decompiler notes under triage/.
8. Draft and submit disclosure.md.
9. Update disclosures/log.md.

Automation Boundaries

Safe to automate:

public patch discovery

source checkout

changed-function extraction

headless decompilation

local builds

sanitizer test runs

fuzzing in scoped labs

crash minimization

report skeleton generation

disclosure checklist

Keep human-supervised:

target authorization decisions

claims of exploitability

public disclosure timing

communication

any test with network reachability outside the lab

any proof that could be adapted for real-world compromise

Suggested Roadmap

High-value impro:

replace the minimal YAML parser with a real YAML parser if the config grows

add a schemas/ directory for finding metadata and disclosure terminal

add a cross-platform new-in script for Windows-nati

add SARIF import/export for source-analysis tools

add MCP adapters for Kali lab execution and Ghidra headless exports

add artifact manifest generation with SHA-256 hashing

add CI that README, target config, finding structure, and disclosure

tables

add a dashboard o status and disclosure state

add Semgrep or CodeQL rules for recurring classes

Current Examples

The checked-in findings demonstrate the intended e shape:

CF: glibc scanf allocation off-by-one analysis,

sanitizer-backed harnesses, and notes.

CMS: OpenSSL CMS AEAD parameter parsing analysis,

DER-generation harness, and related caller review.

C: Linux kernel AF_ALG/splice mapping and

reachability checker.

CNF: V8 JIT type-confusion methodology.

C: ANGLE/WebKit rendering-backend mapping.

These examples are research records. Reproduce or extend them only in authorized
lab en.

项目信息

开发语言：JavaScript

Star 数：1

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕PatchPivot is a defensive variant-analysis workspace for tracking security patches, organizing reproducible research, and carrying findings through responsible disclosure.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。