# Findings: Behavioral Specification

## Scope and environment

Target: `mystery_manifest.py`, the included educational utility.  
Method: black-box invocation, stdout/stderr capture, return-code inspection, and regression tests.  
Dependencies: Python standard library only.

## Verified behavior

| ID | Behavior | Evidence | Confidence |
|---|---|---|---|
| F-01 | With one valid directory argument, the program emits a JSON object to stdout and returns 0. | `normal_directory` probe; `test_valid_directory_emits_json` | High |
| F-02 | The JSON object contains `root`, `file_count`, and `files`. Each file record contains `path`, `size`, and `sha256`. | Normal output schema; source review | High |
| F-03 | File paths in the manifest are relative to the supplied root and use forward slashes in the output. | Nested fixture appears as `nested/events.log` | High for included fixture |
| F-04 | The sample hidden file and `.tmp` file are excluded. | Observed path list; `test_hidden_and_temp_files_excluded` | High for tested fixtures |
| F-05 | A nested regular file is included. | `nested/events.log` appears in output | High for tested fixture |
| F-06 | Changing file bytes while retaining the same filename changes the reported digest in the probe. | `content_sensitivity` probe | High for tested inputs |
| F-07 | Invoking with no argument prints usage to stderr and returns 2. | `missing_argument` probe; unit test | High |
| F-08 | A nonexistent input path prints an error to stderr and returns 1. | `nonexistent_path` probe; unit test | High |

## Output schema

```json
{
  "root": "sample_data",
  "file_count": 2,
  "files": [
    {
      "path": "config.json",
      "size": 37,
      "sha256": "<64-character hexadecimal digest>"
    }
  ]
}
```

The sample above illustrates the schema; the actual `evidence.json` contains observed output for the included fixtures. File sizes and digests depend on exact fixture bytes.

## Error behavior

- Argument count other than one: usage message to stderr, return code 2.
- Input path missing or not a directory: error message to stderr, return code 1.
- Other operating-system read errors: handled as an error message and return code 1.

## Security interpretation

A SHA-256 manifest can support integrity comparison when a trusted baseline is available. It does not prove that a file is safe, establish who created it, or guarantee authenticity. If an attacker can replace both files and the baseline manifest, a matching comparison is not a reliable trust signal. A manifest should be stored and protected separately from the files it monitors when used operationally.

## Limitations and next steps

- This is a small educational script, not a proprietary binary or production-grade forensic tool.
- The probe set does not exhaustively test permissions, symlinks, special files, very large files, race conditions, Unicode normalization, or every operating system.
- The sort order is case-insensitive for traversal order, but case-colliding filenames and platform-specific path behavior are not covered.
- To extend the lab, add probes for hidden directories, uppercase temporary suffixes, empty directories, unreadable files, and a known SHA-256 test vector.
- AI-generated suggestions must be tested before they are presented as findings.