@raishin/vanguard-frontier-agentic 3.2.0 → 3.3.0

package/skills/php/php-runtime-eol-opcache-fpm-review/references/opcache-production-config.md

@@ -0,0 +1,91 @@
+# OPcache production configuration
+
+## Why this matters
+
+OPcache stores precompiled PHP bytecode in shared memory so subsequent
+requests skip parsing and compiling the same script again. In production,
+three misconfigurations defeat this: leaving OPcache disabled (paying full
+compile cost on every request and gaining nothing), leaving timestamp
+validation enabled in a deployment model that expects an immediate cutover
+(serving stale bytecode, or paying an unnecessary per-request filesystem stat
+cost, depending on which way the mismatch runs), and undersizing the cache
+itself (memory or file-count limits below what the codebase actually needs,
+so the accelerator evicts and recompiles under normal load instead of
+reaching a stable steady state). None of these show up in application-code
+review; they live entirely in `php.ini`.
+
+## NORMATIVE: directive behavior per php.net
+
+Per php.net's OPcache configuration reference (`documentation-based`):
+
+- **`opcache.enable`** (default `1`) — enables the opcode cache. When
+  disabled, code is not optimized or cached at all. It cannot be enabled at
+  runtime via `ini_set()` — only disabled; attempting to enable it in a
+  script generates a warning.
+- **`opcache.validate_timestamps`** (default `1`) — if enabled, OPcache
+  checks for updated scripts every `opcache.revalidate_freq` seconds. When
+  disabled, cached scripts are never re-checked against the filesystem;
+  `opcache_reset()`, `opcache_invalidate()`, or a web-server restart is
+  required for filesystem changes to take effect. OPcache may still validate
+  a file's timestamp at compile-time if `opcache.file_update_protection` or
+  `opcache.max_file_size` are set to non-zero values.
+- **`opcache.memory_consumption`** (default `128`, in megabytes) — the size
+  of OPcache's shared-memory storage. The minimum permissible value is `8`;
+  a smaller configured value is clamped up to it.
+- **`opcache.max_accelerated_files`** (default `10000`) — the maximum number
+  of keys (scripts) in OPcache's hash table. The actual value used is the
+  first prime from a fixed internal set (`223, 463, 983, 1979, 3907, 7963,
+  16229, 32531, 65407, 130987, 262237, 524521, 1048793`) that is greater than
+  or equal to the configured value. The minimum is `200`; the maximum is
+  `1000000`; out-of-range values are clamped into that range.
+
+## RECOMMENDATION: production posture by deployment model
+
+These are review recommendations, not php.net mandates — they apply the
+documented directive behavior above to two common deployment models:
+
+- **Immutable-image / container-per-deploy model** — where a new deploy
+  replaces the running container/image wholesale (no in-place file sync to
+  a long-running host): `opcache.validate_timestamps=0` is appropriate,
+  because every deploy already starts a fresh OPcache with the new code —
+  there is no stale-timestamp window to protect against, and skipping the
+  per-request timestamp check removes filesystem overhead. `enable=1` is
+  required either way.
+- **In-place file-sync model** — where code is updated on disk under a
+  long-running PHP-FPM/web-server process without a full process restart:
+  leaving `validate_timestamps=1` (the default) is the safer choice unless
+  the deploy pipeline explicitly calls `opcache_reset()` or
+  `opcache_invalidate()` (or restarts the server) as part of every release.
+  Setting `validate_timestamps=0` in this model without that compensating
+  step means a deploy can silently continue serving stale bytecode.
+
+## Reviewer evidence criteria
+
+- Confirm `opcache.enable=1` in the production `php.ini` (or the effective
+  merged configuration, if directives are set across multiple files);
+  `opcache.enable=0` or the directive's absence at its non-default state is
+  a blocking finding.
+- Determine the deployment model in scope (immutable image vs. in-place
+  sync) from the required inputs, then check `opcache.validate_timestamps`
+  against it per the recommendation above. Flag a mismatch as blocking:
+  `1` in an immutable-image model wastes the per-request stat check;
+  `0` in an in-place-sync model with no compensating invalidation step in
+  the deploy pipeline risks serving stale code.
+- If `validate_timestamps=0` is set, look for the compensating step
+  (`opcache_reset()`/`opcache_invalidate()` call, or a server restart) in
+  the deploy pipeline before treating the configuration as safe.
+- Compare `opcache.memory_consumption` and `opcache.max_accelerated_files`
+  against the actual number and total size of PHP scripts in the codebase.
+  Report undersizing as advisory guidance with a concrete recommended value
+  (not a blocking finding on its own), since undersizing degrades
+  performance rather than correctness.
+- Do not assume a directive's default value applies without checking the
+  actual `php.ini` (or merged configuration) in scope — label a stated
+  default as `documentation-based` and an observed configuration as
+  `repo evidence`.
+
+## Sources
+
+- [PHP: OPcache Configuration](https://www.php.net/manual/en/opcache.configuration.php) — supports the `opcache.enable`, `opcache.validate_timestamps`, `opcache.memory_consumption`, and `opcache.max_accelerated_files` descriptions and default/clamping values above.
+
+Last verified: 2026-07-16.

package/skills/php/php-runtime-eol-opcache-fpm-review/references/php-fpm-pool-tuning.md

@@ -0,0 +1,87 @@
+# PHP-FPM pool tuning
+
+## Why this matters
+
+PHP-FPM's process manager controls how many PHP worker processes exist and
+how long each one lives. Two settings dominate the production risk surface:
+`pm` together with `pm.max_children` bounds worker concurrency, so an
+unbounded or unsized value lets a traffic spike spawn more workers than the
+host has memory for, exhausting the host outright; and `pm.max_requests`
+bounds a worker's lifetime in requests served, so leaving it unlimited lets a
+slow memory leak in application or third-party code degrade a worker (and
+eventually the pool) indefinitely instead of being recycled away. Neither
+failure is visible in application-code review — both live in the FPM pool
+configuration file.
+
+## NORMATIVE: directive behavior per php.net
+
+Per php.net's PHP-FPM configuration reference (`documentation-based`):
+
+- **`pm`** (mandatory, no default) — chooses how the process manager
+  controls the number of child processes. Possible values:
+  - `static` — the number of child processes is fixed at `pm.max_children`.
+  - `dynamic` — the number of child processes varies at runtime between `pm.min_spare_servers`/`pm.max_spare_servers`, starting from `pm.start_servers`, up to a ceiling of `pm.max_children`.
+  - `ondemand` — processes spawn only when a request arrives, rather than `pm.start_servers` being started when the service starts.
+- **`pm.max_children`** (mandatory, no default) — the number of child
+  processes created when `pm=static`, and the *maximum* number of child
+  processes created when `pm=dynamic` or `pm=ondemand`. This directive sets
+  the hard limit on the number of simultaneous requests the pool will serve
+  — equivalent to Apache's `MaxClients` directive under `mpm_prefork`, or the
+  `PHP_FCGI_CHILDREN` environment variable in the original PHP FastCGI.
+- **`pm.max_requests`** (default `0`, meaning unlimited) — the number of
+  requests each child process executes before it is recycled (killed and
+  respawned). Documented as useful for working around memory leaks in
+  third-party libraries. A value of `0` means a worker serves requests
+  indefinitely, with no automatic recycling.
+
+## RECOMMENDATION: sizing and review posture
+
+These are review recommendations applying the documented directives above,
+not php.net mandates for a specific numeric value:
+
+- **`pm.max_children` must be evidently bounded by available memory.** As a
+  rough check: multiply `pm.max_children` by a representative single-worker
+  memory footprint (observed or estimated for the application) and confirm
+  the product does not exceed the memory actually available to the pool's
+  host or container. A `pm.max_children` value set without any apparent
+  relationship to available memory (an arbitrary round number carried over
+  from a different host size, or left at a packaging default) is a
+  resource-exhaustion risk under a traffic spike.
+- **Prefer `dynamic` or `ondemand` over an oversized `static` pool** for
+  workloads with variable traffic, so idle capacity is not permanently
+  reserved; `static` is reasonable when load is genuinely constant and the
+  host is sized for the fixed worker count.
+- **`pm.max_requests` should be a nonzero, workload-appropriate value** in
+  production, so a worker with a slow leak is recycled before it degrades
+  the pool. Leaving it at the default `0` (unlimited) is acceptable only with
+  an explicit, documented rationale (e.g. the application and every
+  third-party library in its request path are already known leak-free under
+  sustained load) — otherwise treat unbounded `pm.max_requests` as a blocking
+  finding alongside unbounded `pm.max_children`.
+
+## Reviewer evidence criteria
+
+- Confirm `pm` is explicitly set (it is mandatory with no default) to one of
+  `static`, `dynamic`, or `ondemand`, and matches the stated workload shape.
+- Confirm `pm.max_children` is set (mandatory, no default) and check it
+  against the rough memory-bound calculation above; flag a value with no
+  apparent sizing rationale, or one clearly exceeding available host/
+  container memory, as a blocking finding.
+- If `pm=dynamic`, confirm `pm.start_servers`, `pm.min_spare_servers`, and
+  `pm.max_spare_servers` are all set consistently with `pm.max_children`
+  (each within a sane range relative to the ceiling), since a missing or
+  contradictory value among this triad undermines the sizing already done
+  for `pm.max_children`.
+- Confirm `pm.max_requests` is set to a nonzero value, or that an explicit
+  documented rationale exists for leaving it at `0`; flag an unexplained `0`
+  as a blocking finding.
+- Label an observed pool configuration `repo evidence`, a php.net-documented
+  default or semantic `documentation-based`, and any memory-footprint
+  estimate used for the sizing check `inference` — state which is which
+  rather than presenting an estimate as a measured fact.
+
+## Sources
+
+- [PHP: PHP-FPM Configuration](https://www.php.net/manual/en/install.fpm.configuration.php) — supports the `pm`, `pm.max_children`, and `pm.max_requests` descriptions, mandatory/default-value status, and the `MaxClients`/`PHP_FCGI_CHILDREN`/`PHP_FCGI_MAX_REQUESTS` equivalences above.
+
+Last verified: 2026-07-16.

package/skills/php/php-runtime-eol-opcache-fpm-review/references/php-version-lifecycle.md

@@ -0,0 +1,102 @@
+# PHP version lifecycle
+
+## Why this matters
+
+A PHP branch that has left php.net's supported window stops receiving fixes of
+any kind once it reaches end of life (EOL) — including for actively exploited
+vulnerabilities — while a branch in its security-only window still receives
+critical security fixes but no bug fixes, and is itself counting down to its
+own EOL. A service can look fully healthy at the application-code level (green
+tests, current dependencies) while the runtime underneath it has already
+crossed one of these boundaries. This file is the sole source the skill uses
+for those dates; every version-lifecycle claim in a review must resolve to a
+row below, and to no other memory or estimate.
+
+## NORMATIVE: php.net's support policy
+
+Per php.net's Supported Versions page (`documentation-based`):
+
+- Each release branch of PHP is fully supported for **two years** from its
+  initial stable release. During this period, reported bugs and security
+  issues are fixed and released in regular point releases.
+- After that two-year active-support period, each branch is then supported
+  for **two additional years** for critical security issues only. Releases
+  during this window are made on an as-needed basis — there may be multiple
+  point releases, or none, depending on the number of reports.
+- After the combined four-year window (two years active plus two years
+  security-only), a branch is **end of life (EOL)**: no further fixes of any
+  kind are published for it, including for actively exploited
+  vulnerabilities.
+
+## NORMATIVE: current per-branch dates
+
+Per php.net's Supported Versions page, the currently listed branches and
+their published dates are:
+
+| Branch | Active support until | Security support until (EOL) |
+|---|---|---|
+| PHP 8.2 | 31 Dec 2024 | 31 Dec 2026 |
+| PHP 8.3 | 31 Dec 2025 | 31 Dec 2027 |
+| PHP 8.4 | 31 Dec 2026 | 31 Dec 2028 |
+| PHP 8.5 | 31 Dec 2027 | 31 Dec 2029 |
+
+Reading this table for a review:
+
+- A branch is in **active support** if the current review's target/committed
+  version date is before its "Active support until" date.
+- A branch is in **security-only support** if that date is on or after
+  "Active support until" but before "Security support until."
+- A branch is **EOL** once that date reaches or passes "Security support
+  until" — no fixes of any kind are published past that point.
+
+Any PHP version not listed in php.net's current supported-versions table
+(either older than the branches php.net still lists, or a malformed/future
+version string) has no dates in this file — say the evidence is missing
+rather than inferring a status.
+
+## Reviewer evidence criteria
+
+- Resolve the exact PHP version from the strongest available evidence:
+  a running-version banner or `phpversion()`/`php -v` output outranks a
+  Dockerfile/base-image tag, which outranks a loose Composer `require.php`
+  constraint (e.g. `^8.2` does not tell you which point release is actually
+  deployed, only the minimum branch). State which evidence tier the version
+  claim rests on.
+- Match the resolved branch against the table above exactly; do not round a
+  point release to a different branch or assume a branch's status from a
+  prior review.
+- Classify the branch precisely as active support, security-only (cite the
+  exact security-support-until date), or EOL (cite the exact date it was
+  reached) — never collapse these into an undifferentiated "outdated" label.
+- Determine the branch's **current phase** by comparing this file's published
+  cutoff dates against the review date — the current date, or an explicitly
+  supplied review/support-horizon date when one is given. This file's
+  per-branch dates are the fixed ground truth (sourced from php.net, never
+  invented, rounded, or extrapolated); only the comparison against the review
+  date is a review-time judgment, so a branch correctly transitions from
+  active support to security-only to EOL as the review date passes each
+  published cutoff.
+- For a security-only branch, compare its "Security support until" date
+  against both the review date and the review's stated release/support
+  horizon. If EOL has already been reached, or that date falls within the
+  horizon with no tracked upgrade plan, this is a blocking finding per the
+  skill's decision gates, not merely advisory.
+- For an EOL branch, the finding is blocking unconditionally — there is no
+  "well-maintained otherwise" exception, since EOL means no fixes of any kind
+  are published, including for actively exploited vulnerabilities.
+
+## NORMATIVE vs. RECOMMENDATION
+
+The support-policy structure and the per-branch dates above are NORMATIVE —
+sourced directly from php.net and not to be altered, rounded, or
+extrapolated. The recommended target version for an upgrade (e.g. "move to
+the newest branch still in active support") is a RECOMMENDATION: name a
+target that is currently in active support per the table above, but leave the
+final choice, timeline, and any compatibility work to the owning engineering
+team.
+
+## Sources
+
+- [PHP: Supported Versions](https://www.php.net/supported-versions.php) — supports the two-year active-support / two-year security-only / EOL support-policy structure and the per-branch dates for PHP 8.2 through 8.5 above.
+
+Last verified: 2026-07-16.

package/skills/php/php-session-upload-deserialization-review/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: php-session-upload-deserialization-review
+description: Use this skill to statically review PHP code for object-injection risk from unserialize() on untrusted input, session fixation/hijacking from missing session_regenerate_id() or weak session cookie hardening, and unsafe file-upload handling that trusts the client or stores/executes uploads inside the webroot. Use when reviewing a PHP application for deserialization, authentication-session, or upload-handling security issues. Static review only; it never executes payloads, uploads, or requests against any system, and every unserialize()/session/upload claim is grounded in the current php.net manual rather than memory.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-16"
+  category: security
+  lifecycle: experimental
+---
+
+# PHP Session, Upload, and Deserialization Review
+
+## Purpose
+
+Review PHP source for the three failure modes where the language's own deserialization, session, and file-upload primitives are used in a way php.net's own manual explicitly warns against: `unserialize()` called on untrusted input (object injection, potentially remote code execution), a session that is not regenerated after a privilege change or that ships without cookie hardening (fixation/hijacking), and an upload handler that trusts the client or stores/executes accepted files inside the webroot.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review any code path that calls `unserialize()`, or a library/cache/session backend that transparently unserializes stored data, for object-injection risk;
+- review whether a login, role-elevation, or password-reset path correctly regenerates the session id and whether session cookie hardening (`use_strict_mode`, `httponly`, `secure`, `samesite`) is configured;
+- review a file-upload handler for client-trust, storage-location, or size/type/count-limit gaps.
+
+## When not to use
+
+Do not use this skill for:
+
+- designing or approving a backend authorization/permission model — this skill only checks whether a privilege change triggers session regeneration, not whether the privilege model itself is correct; hand that off to the owning backend/platform specialist.
+- executing, crafting, or sending any deserialization payload, session-fixation request, or file upload against any live, sandbox, or staging system. This skill is static review only.
+- issuing a compliance or audit attestation from an OWASP category mapping; the mapping is a classification aid, never a determination.
+
+## Preconditions
+
+- The code paths that call `unserialize()`, plus the source of the data passed to each call (request body/query/cookie, cache backend, queue message, database column).
+- The authentication/session-management code, specifically where `session_start()`, `session_regenerate_id()`, and `$_SESSION` writes occur relative to a login, role change, or password reset.
+- The active `session.*` INI settings in scope (`session.use_strict_mode`, `session.cookie_httponly`, `session.cookie_secure`, `session.cookie_samesite`) from `php.ini`, `.htaccess`, or runtime `ini_set()` calls.
+- The upload-handling code: how `$_FILES` is validated, where accepted files are stored, and the `upload_max_filesize`/`post_max_size`/`max_file_uploads` configuration in effect.
+- The PHP version in scope (`session.cookie_samesite` requires PHP 7.3+; destructor-on-fatal-error behavior changed at PHP 5.3.10).
+
+## Lean operating rules
+
+- Flag any `unserialize()` call on untrusted input regardless of `allowed_classes` — the manual's caution applies unconditionally, and `allowed_classes` narrows instantiable classes without making the call safe.
+- Name the reachable magic-method surface (`__wakeup()`, `__unserialize()`, `__destruct()`) for any class an untrusted `unserialize()` call could instantiate; PHP invokes these automatically on the reconstructed object or during the shutdown sequence.
+- Recommend `json_decode()`/`json_encode()` as the default remediation for untrusted data interchange unless serialized PHP objects are confirmed necessary.
+- Require `session_regenerate_id(true)` before the authenticated flag is written to `$_SESSION` on every login/elevation/reset path; a regeneration call placed after that write is a finding, not a pass.
+- Check `session.use_strict_mode`, `session.cookie_httponly`, `session.cookie_secure`, and `session.cookie_samesite` individually and explicitly; never infer hardening from defaults, since `use_strict_mode` is disabled by default.
+- Require upload handlers to validate the file's actual content server-side (never the client-supplied `$_FILES[...]['type']` or filename alone), store accepted files outside any web-servable path, and enforce `upload_max_filesize`, `post_max_size`, and `max_file_uploads`.
+- Never request, echo, store, or reproduce a secret, credential, session id, token, or PII found in reviewed code; redact-and-flag any such string.
+- Label every claim `repo evidence` (seen in the reviewed code) or `documentation-based` (current php.net manual); never assert a documented API behavior from memory.
+
+## Context7 documentation protocol
+
+This skill's `allowed-tools` is limited to `Read`, `Grep`, and `Glob` — it does not include a live documentation-lookup tool, so grounding is done against the bundled, php.net-sourced reference files rather than a runtime Context7 call. `unserialize()`, the `session.*` INI directives, and the upload-handling behaviors reviewed here are core-language documentation, not a third-party library whose API shifts release to release, so the bundled references (each fetched directly from php.net, with its own Sources section and verification date) are the grounding source of record. If a review surfaces a claim about PHP behavior not covered by the bundled references — a different function, a different INI directive, a different PHP version's behavior — do not assert it from memory; say the claim is unverified against a specific php.net page and escalate for direct verification rather than guessing.
+
+## Workflow
+
+1. Enumerate every `unserialize()` call site in scope and trace the data source of its argument; classify each as untrusted-input-reachable or not.
+2. For each untrusted-input-reachable `unserialize()` call, identify classes it could instantiate and check for `__wakeup()`, `__unserialize()`, and `__destruct()` magic methods that would fire automatically — see [Unserialize object injection](references/unserialize-object-injection.md).
+3. For each authentication/privilege-elevation path, confirm `session_regenerate_id(true)` is called before `$_SESSION` carries the authenticated flag, and check the four session-hardening directives — see [Session security](references/session-security.md).
+4. For each upload handler, confirm server-side content validation, non-webroot storage, and enforced size/type/count limits — see [File upload security](references/file-upload-security.md).
+5. Emit findings with evidence tiers, exploit/failure narratives, remediation, verification steps, and OWASP category mappings; hand off any authorization-model or infrastructure-scoped issue to the owning specialist.
+
+## Decision gates
+
+- Block only on a demonstrated untrusted-input-reachable `unserialize()` call, a missing/misordered `session_regenerate_id()` call, a missing `session.use_strict_mode`, or an upload handler that trusts the client, stores inside the webroot, or lacks enforced limits.
+- Every `unserialize()`, session-directive, or upload-limit claim cites the current php.net manual (`documentation-based`) or the reviewed code (`repo evidence`) — never memory.
+- Every OWASP mapping names the specific edition and category cited and is labeled a classification aid, never a compliance determination.
+- Every authorization-model-design or infrastructure-scoped finding is handed off, not adjudicated here.
+
+## Evidence classification
+
+Label each finding `repo evidence` (seen directly in the reviewed code or configuration) or `documentation-based` (the current php.net manual). This skill does not use `context7-grounded` (no Context7 tool in scope) and does not use `inference` for a documented API behavior — an undocumented or unverifiable behavior claim must be flagged as unverified rather than guessed.
+
+## Security and privacy constraints
+
+Static review only. Never request, transmit, store, or reproduce a secret, credential, session id, token, or PII found in reviewed code or configuration; treat any such string as a redact-and-flag finding. Never execute a deserialization payload, replay or forge a session id, upload a file, or send any request to a live, sandbox, or staging system. OWASP category mappings are classification aids, never compliance attestations.
+
+## Escalation conditions
+
+Escalate to incident response on any evidence the failure is already live: an object-injection payload observed in logs, a reachable uploaded web shell, or an observed session id reused across a privilege boundary. Escalate backend authorization-model design and infrastructure-scoped findings (webroot layout, TLS termination) to their owning specialist rather than adjudicating them here.
+
+## References
+
+Load these only when needed:
+
+- [Unserialize object injection](references/unserialize-object-injection.md) — why `unserialize()` on untrusted input is unsafe regardless of `allowed_classes`, the magic-method attack surface, and the `json_decode()` remediation.
+- [Session security](references/session-security.md) — `session_regenerate_id()` ordering around privilege changes and the four session cookie-hardening directives.
+- [File upload security](references/file-upload-security.md) — client-trust, storage-location, and size/type/count-limit review criteria for upload handlers.
+
+Each reference file carries its own Sources section citing the exact php.net (or OWASP) page backing its claims — there is no separate primary-source ledger file in this skill.
+
+## Response minimum
+
+Return, at minimum:
+
+- the call site/path in scope and, per finding, the failure class (`object-injection` / `session-fixation-hijacking` / `unsafe-upload`) and evidence tier;
+- the exploit or failure narrative (how the reachable input reaches a wrong outcome);
+- concrete remediation and an exact verification step;
+- the OWASP category mapping, labeled as a classification aid;
+- any authorization-model or infrastructure-scoped handoffs and incident-response escalation.
+
+## Anti-goals
+
+- Do not treat `allowed_classes` as a mitigation for `unserialize()` on untrusted input; the manual's caution is unconditional.
+- Do not design or approve a backend authorization/permission model; hand it off.
+- Do not execute any payload, upload, or request against any live, sandbox, or staging system.
+- Do not assert `unserialize()`, session-directive, or upload-limit behavior from memory; ground every such claim in the current php.net manual.
+- Do not echo, store, or reproduce any secret, session id, token, or PII found during review.

package/skills/php/php-session-upload-deserialization-review/metadata.json

@@ -0,0 +1,20 @@
+{
+  "id": "php-session-upload-deserialization-review",
+  "name": "PHP Session, Upload & Deserialization Security Review",
+  "type": "skill",
+  "provider": "php",
+  "harnesses": ["claude-code", "cursor", "codex", "gemini", "kiro", "other"],
+  "summary": "Skill for reviewing PHP application-security seams: user-reachable unserialize() object injection (allowed_classes is insufficient), session fixation/hijacking hardening (session_regenerate_id, use_strict_mode, cookie flags), and unsafe file-upload handling, each mapped to an OWASP category and the php.net-documented fix.",
+  "source_type": "original",
+  "official_docs": [
+    "https://www.php.net/manual/en/function.unserialize.php",
+    "https://www.php.net/manual/en/session.security.php",
+    "https://www.php.net/manual/en/features.file-upload.common-pitfalls.php",
+    "https://owasp.org/www-project-top-ten/"
+  ],
+  "security_notes": "Static-review-only skill: Read/Grep/Glob, no execution and no network. Never runs deserialization payloads, uploads, or exploits against any live or staging system. Any credential- or PII-shaped string is a redact-and-flag finding, never echoed. Every unserialize()/session/upload claim is grounded in current php.net documentation, not memory.",
+  "last_verified": "2026-07-16",
+  "path": "skills/php/php-session-upload-deserialization-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/php/php-session-upload-deserialization-review/references/file-upload-security.md

@@ -0,0 +1,119 @@
+# File upload security
+
+## Why this matters
+
+An upload handler is the one place in most PHP applications where a client
+supplies content the server will store, and often later serve, on its own
+filesystem. Every trust decision the manual warns against — believing the
+client's stated MIME type, believing the client's filename, skipping the
+configured size/count ceilings, or placing accepted content somewhere the
+web server will execute it — turns a routine upload feature into a path for
+an attacker to plant and run a web shell, exhaust server resources, or read
+files the application never meant to expose.
+
+## NORMATIVE: configuration ceilings gate every upload
+
+Per the php.net manual's common-pitfalls guidance for file uploads:
+
+- **`upload_max_filesize`** caps the size PHP will accept per file: "The
+  `MAX_FILE_SIZE` item cannot specify a file size greater than the file size
+  that has been set in the `upload_max_filesize` in the php.ini file. The
+  default is 2 megabytes." A form-field `MAX_FILE_SIZE` hint is a
+  client-side convenience only; the server-enforced ceiling is
+  `upload_max_filesize`.
+- **`post_max_size`** must accommodate the request as a whole: "If
+  `post_max_size` is set too small, large files cannot be uploaded. Make
+  sure you set `post_max_size` large enough." A `post_max_size` smaller than
+  `upload_max_filesize` silently caps effective upload size below what
+  `upload_max_filesize` alone suggests.
+- **`max_file_uploads`** bounds how many files one request can carry: "The
+  `max_file_uploads` configuration setting controls the maximum number of
+  files that can [be] uploaded in one request. If more files are uploaded
+  than the limit, then `$_FILES` will stop processing files once the limit
+  is reached" — silently, not with an error the handler is guaranteed to
+  check for.
+- **`memory_limit`**, **`max_execution_time`**, and **`max_input_time`** must
+  also be sized for uploads: the manual specifically notes `max_input_time`
+  "sets the maximum time, in seconds, the script is allowed to receive
+  input; this includes file uploads. For large or multiple files, or users
+  on slower connections, the default of `60` seconds may be exceeded,"
+  causing an otherwise-valid upload to fail partway through.
+
+A review must confirm these are set deliberately (not left at silent
+defaults that either reject legitimate uploads or, in the case of
+`max_file_uploads`, silently truncate a batch without the handler noticing).
+
+## NORMATIVE: do not trust which file you operate on
+
+The manual's common-pitfalls page states plainly: "Not validating which file
+you operate on may mean that users can access sensitive information in
+other directories." This is the manual's own framing of path-traversal and
+client-trust risk in upload handling — a filename or path is untrusted input
+like any other and must be validated, not built into a filesystem operation
+directly. The manual separately cautions that "due to the large amount of
+directory listing styles we cannot guarantee that files with exotic names
+(like containing spaces) are handled properly," reinforcing that the
+client-supplied filename cannot be relied on to behave predictably and
+should not be used to construct a storage path or to make a security
+decision (such as inferring file type from its extension).
+
+## RECOMMENDATION: validate content, not client claims; store outside the webroot
+
+The manual's guidance above establishes the principle — validate the file
+you actually operate on — but does not itself specify a validation
+algorithm or a storage location; the following are this skill's operating
+recommendations applying that principle, to be checked as reviewer evidence
+criteria below rather than cited as separate manual quotations:
+
+- Treat `$_FILES[...]['type']` (client-reported MIME type) and
+  `$_FILES[...]['name']` (client-reported filename) as untrusted metadata
+  only. A security decision — what kind of file this is, whether it is
+  acceptable — must be made from the file's actual content on the server,
+  not from either client-supplied field.
+- Store accepted uploads outside any path the web server will serve
+  directly, and generate the stored filename server-side rather than
+  reusing the client-supplied name verbatim, closing both the
+  path-traversal risk above and the risk of an executable extension being
+  preserved into a servable location.
+- Never `include()`, `require()`, or otherwise execute an uploaded file as
+  PHP code, and never configure the storage directory to be
+  script-executable by the web server.
+
+## Reviewer evidence criteria
+
+For each upload handler in scope:
+
+- Confirm `upload_max_filesize`, `post_max_size` (sized larger than
+  `upload_max_filesize`), and `max_file_uploads` are set to deliberate,
+  documented values rather than left at framework/PHP defaults without
+  review, and confirm the handler does not assume a client-side
+  `MAX_FILE_SIZE` hint is enforced.
+- Confirm the handler checks the actual number of files processed against
+  what the client claims to have sent, given that `$_FILES` silently stops
+  populating once `max_file_uploads` is reached.
+- Confirm the handler validates the file's real type/content server-side,
+  not `$_FILES[...]['type']` or the client filename's extension alone.
+- Confirm accepted files are stored outside any web-servable path, with a
+  server-generated filename, not the client-supplied one used verbatim in
+  a filesystem path.
+- Confirm no code path `include()`s, `require()`s, or otherwise executes an
+  uploaded file, and that the storage location is not configured as
+  script-executable.
+- Treat trusting client-supplied MIME type/filename for a security decision,
+  storing inside the webroot, or having no enforced size/type/count limit as
+  a blocking finding.
+
+## Applicable versions
+
+The `upload_max_filesize` default (2 megabytes) and the `max_file_uploads`
+silent-truncation behavior described above are current php.net manual
+guidance as of this review; re-verify against the live manual page before
+citing an exact default value, since PHP distribution defaults (and
+distro-specific `php.ini` overrides) can differ from the documented
+upstream default.
+
+## Sources
+
+- [PHP Manual — Common Pitfalls (file uploads)](https://www.php.net/manual/en/features.file-upload.common-pitfalls.php) — supports the `upload_max_filesize` default and `MAX_FILE_SIZE` client-hint framing, the `post_max_size` sizing guidance, the `max_file_uploads` silent-stop behavior, the `max_input_time` upload-duration caution, and the "not validating which file you operate on" and "exotic names" client-trust cautions.
+
+Last verified: 2026-07-16.