# AI-Assisted Software Reverse Engineering \& Behavioral Analysis

**Project type:** Independent cybersecurity lab  
**Focus:** Python, black-box testing, AI-assisted hypothesis generation, SHA-256, JSON, evidence-based analysis  
**Safety scope:** A small, benign local file-manifest utility operating only on files in a directory supplied by the operator.

## Executive summary

This lab demonstrates a repeatable workflow for investigating an unfamiliar utility without relying on its implementation details at the start of analysis. The analyst treats the target as a black box, forms hypotheses about its input handling and output, runs controlled probes, records observable evidence, and validates the resulting behavioral specification with regression tests. An AI assistant is used as a hypothesis-generation and documentation aid; it is not treated as proof.

The included `mystery\_manifest.py` is the educational target. It walks a directory and emits a JSON manifest with relative paths, byte sizes, and SHA-256 digests. The accompanying probe harness exercises normal input, invalid invocation, a nonexistent directory, and content changes. The tests turn the observed behavior into a repeatable verification suite.

> This is a self-contained educational simulation, not analysis of a third-party commercial product or a compiled executable. That scope is intentional: it makes the methodology reproducible and keeps testing safe.

## Repository contents

* `mystery\_manifest.py` — benign target utility under investigation.
* `probe\_target.py` — repeatable black-box probe harness; prints a JSON evidence record.
* `test\_reverse\_engineering.py` — regression tests for verified behavior.
* `sample\_data/` — fixtures covering normal, nested, hidden, and temporary files.
* `ai\_analysis\_workflow.md` — prompts and guardrails for using an LLM responsibly.
* `findings.md` — evidence-linked behavioral specification and limitations.
* `evidence.json` — captured output from the included probe harness.

## Requirements

* Python 3.10 or newer
* No third-party packages
* Optional: an LLM of your choice for the prompts in `ai\_analysis\_workflow.md`. The project runs without an API key or network access.

## Run the project

From this directory:

```bash
python mystery\_manifest.py sample\_data
python probe\_target.py
python -m unittest -v
```

To save probe output to a file:

```bash
python probe\_target.py > evidence.json
```

The output is deterministic for a stable input directory except that the temporary content-sensitivity probe uses a randomly named temporary directory internally; that path is not emitted in the probe summary.

## Reverse-engineering workflow

1. **Define scope.** Use only the included benign target and fixture directory.
2. **Inspect the interface.** Record expected arguments, output channels, and return codes before inferring internal behavior.
3. **Probe one variable at a time.** Test a normal directory, missing argument, invalid path, hidden files, temporary suffixes, nested files, and content changes.
4. **Capture evidence.** Preserve stdout, stderr, return codes, observed paths, and digest comparisons.
5. **Ask AI for hypotheses.** Provide only observed evidence and ask for multiple explanations, confidence levels, and a discriminating test for each.
6. **Verify independently.** Run the proposed tests. Promote a hypothesis to a finding only when observations support it.
7. **Specify behavior.** Document inputs, output schema, error behavior, edge cases, and limitations.
8. **Regression test.** Encode the verified specification in unit tests so future changes are detectable.

## AI use and integrity

AI is a reasoning aid, not an evidence source. Do not ask a model to assert implementation facts from output alone. Ask it to label statements as **observation**, **hypothesis**, or **unknown**, then design experiments to discriminate among hypotheses. Do not submit secrets, private files, or third-party proprietary code to a hosted model without authorization. The prompts are included in `ai\_analysis\_workflow.md`; all final claims in `findings.md` are tied to the local probes or tests.

## Security and ethical boundaries

* Analyze only software you own or are explicitly authorized to assess.
* This sample does not exploit vulnerabilities, evade detection, persist, access a network, or modify files.
* The target reads files only to calculate their size and digest.
* Do not point the tool at sensitive directories; use the included fixtures.
* Findings are limited to the tested version and environment.