A Modified File Is Evidence, Not a Verdict: Practical File Integrity for PHP Applications

A file-integrity check reports:

MODIFIED
src/Example/Service.php

What does that mean?

Exactly one thing:

The current file does not match the expected bytes represented by the
reference hash.

It does not automatically mean malware. It does not automatically
mean a failed update. It does not even prove the expected reference is
the correct reference for this installation.

Good integrity tooling is precise about what it knows.

How hash manifests work

A release can include a mapping of file paths to cryptographic
digests:

{
  "src/Example/Service.php": "a1b2...",
  "src/Example/Controller.php": "c3d4..."
}

During a health check:

1. locate the expected file;
2. calculate its current SHA-256;
3. compare with the manifest;
4. classify the result.

Typical states:

MATCH      current hash equals expected hash
MODIFIED   file exists but hash differs
MISSING    expected path does not exist
UNREADABLE file exists but cannot be read

These states are objective and useful.

Do
not invent “unexpected file” findings without a complete inventory

A manifest often lists files that belong to one package.

The containing directory may also include legitimate files from:

• other packages;
• generated caches;
• local configuration;
• extension systems.

If the manifest is not defined as a complete directory inventory, a
tool should not scan every extra file and label it suspicious.

This avoids false positives.

Why legitimate
modifications happen

Common reasons include:

Manual hotfix

An administrator edited production directly.

Hosting modification

A deployment or security layer rewrote a file.

Incomplete package
replacement

Some files came from a newer version while others remained old.

Local customization

The installation intentionally differs from vendor release files.

Generated content in the
wrong place

A tool wrote dynamic content into a packaged path.

Only after considering these possibilities should you escalate toward
compromise investigation.

Why modified files still
matter

Even legitimate modifications create operational risk.

A manual hotfix may disappear during the next upgrade.

A partial release may produce code that no vendor tested
together.

A local customization may explain why a bug cannot be reproduced
elsewhere.

So the correct response is not “ignore unless malware.”

It is “identify and document the reason.”

The reference
manifest must be trustworthy

If both the file and its expected hash can be modified by the same
unauthorized actor, local integrity verification has limitations.

A stronger model retains trusted release manifests outside the
writable production path or obtains them from a trusted package
source.

For ordinary support and deployment validation, packaged manifests
are still valuable—but understand the trust boundary.

Package-level
and installation-level checks solve different problems

A package checksum answers:

Is this ZIP exactly the release artifact I expected?

A file manifest answers:

Do the installed files represented by this manifest still match their
expected release bytes?

Use both where appropriate.

A ZIP can verify correctly and still be deployed incompletely.

Installed files can all match their manifest while the ZIP a customer
downloaded differs from the one you intended to publish.

A safe investigation
workflow

When a mismatch appears:

1. Record the path and hashes

Keep expected and current digest.

2. Confirm the package version

Make sure the manifest corresponds to the installed version.

3. Compare the actual content

Use a text diff for source files.

For example:

diff -u expected/Service.php current/Service.php

4. Check deployment history

Was there a hotfix, interrupted upload or hosting restore?

5. Check timestamps carefully

Modification time can provide context, but it is not cryptographic
evidence and can be changed.

6. Restore only from a
trusted source

Do not overwrite production just because the diagnostic says
“modified.” First confirm the expected file is actually the desired
file.

Missing files deserve
similar restraint

An expected file can be missing because:

• upload skipped it;
• permissions prevented extraction;
• antivirus/security tooling removed it;
• someone deleted it manually;
• deployment package was incomplete.

The state is important, but the root cause still needs
investigation.

Integrity checks after
upgrades

One of the best times to run a file check is immediately after a
core/plugin/add-on upgrade.

You want to catch:

• missing new files;
• stale old package files that should have been replaced;
• partial upload;
• modified files that survived unexpectedly.

Record the clean state after deployment so later changes are easier
to interpret.

Performance considerations

Hashing many files consumes I/O and CPU.

For a normal add-on manifest this is usually manageable, but very
large installations should avoid repeatedly hashing the entire
filesystem on every page request.

Run integrity checks deliberately, cache bounded results if useful,
and keep the operation out of latency-sensitive front-end paths.

Never “repair” silently

An integrity tool should not automatically replace modified files
from the internet.

That creates several risks:

• wrong version;
• broken local customization;
• supply-chain dependency;
• permission/ownership changes;
• loss of forensic evidence.

A safer report says:

MODIFIED
Expected SHA-256: ...
Current SHA-256: ...
Automatic replacement: not attempted

Then the administrator chooses the trusted recovery source.

Integrity is a
comparison, not a security score

File integrity works well because it asks a narrow question with a
precise answer.

Keep it narrow.

Do not turn one changed file into a made-up “security score
42/100.”

Show the path, reference, current state and package ownership.

A modified file is evidence.

Good diagnostics preserve that evidence long enough for a human to
understand what happened.