Upgrade and Migration Guide

Source and package versions

One AIWAF repository. Python: py/aiwaf/ · Node.js: js/ · Rust/WASM: rust/ · Java: java/. Source and canonical README. Versions shown describe the source checkout; package releases are independent. Current Python/Node source targets are aiwaf 1.1.8 (Python) and aiwaf 1.1.5 (npm), with Rust/Python 0.2.7 and WASM 0.2.5 and Java 1.3.5. Sandbox guides retain their separately pinned builds.

All maintained packages use the AIWAF monorepo. Each package releases independently. Compare the installed version, source manifest, and release notes for your runtime before upgrading; source versions are not confirmation that a registry release exists.

Upgrade sequence

  1. Record installed versions, enabled middleware, exemptions, configuration, state backend, model path, and proxy behavior. Back up persisted state, configuration, and models.
  2. Upgrade one runtime in staging using its package manager or build from a reviewed source revision. Preserve the matching dependency lockfiles.
  3. Apply package-name and configuration changes below. Regenerate manifests from the live application after its routes are registered.
  4. Migrate blocklist state with the runtime's supported command; inspect counts, expiry, reasons, and exemptions afterward.
  5. Regenerate unsupported models with the current trainer. Verify schema, feature order, output location, and load diagnostics.
  6. Test normal public traffic, intentional blocks, rate boundaries, intended exemptions, and actual response logging. Test across workers when state is shared.
  7. Deploy code, configuration, and compatible state/models together. Reload workers and repeat checks. Keep a compatible rollback snapshot.

Node.js package name

The npm middleware package is now aiwaf. Replace the old dependency and imports; regenerate the lockfile and test every adapter entrypoint your application uses.

npm uninstall aiwaf-js
npm install aiwaf
const aiwaf = require('aiwaf');
app.use(aiwaf({ AIWAF_MIDDLEWARES: ['all'] }));

aiwaf-wasm remains a separate package. Installing it does not replace Node framework middleware. Check normalized aliases and defaults in the configuration reference before moving settings between versions.

Python reputation and blocklist data

Python 1.0.7 introduced weighted reputation, progressive temporary blocking, expiry, and richer metadata. Legacy blocklist compatibility is backend-aware, including CSV schema detection and conversion of imported permanent blocks. Use the same checkout, environment, and backend configuration as your application:

aiwaf blocklist migrate

When multiple frameworks are installed, choose an explicit prefix such as aiwaf flask --help or aiwaf fastapi --help. --framework and --app are route-discovery options for aiwaf init. Do not manually reinterpret old CSV columns or assume historical permanent blocks retain identical enforcement semantics. Back up first and compare the resulting entries.

Python models and Rust acceleration

Persisted Python runtime models are JSON. Pickle, joblib, and executable Python-object artifacts are unsupported; use representative logs and the current trainer to create a new model. Check minimum log thresholds rather than forcing production training on a tiny sample.

Python 1.1.8 requires aiwaf-rust>=0.2.7; the Rust extra remains an installation alias. The explicit native request engine validates its required APIs at startup. Installing the companion does not replace an existing legacy middleware chain. Upgrade both packages in the deployed interpreter and verify the real adapter after restarting workers.

python -m pip install --upgrade 'aiwaf[flask,rust]'
# Use the extra matching your application.
aiwaf flask train --help
aiwaf flask model --help

Route manifests and import targets

aiwaf init --framework flask --app app:app
aiwaf init --framework flask --app app:create_app
aiwaf init --framework fastapi --app app:app
aiwaf init --framework django --settings project.settings

--app app.py is invalid. The target must be a module and application object/factory. Run discovery in the application's environment; it imports the application. Do not carry a stale manifest across route changes.

Java 1.2 and 1.3 changes

Java 1.2 adds scoped per-engine storage, distributed Redis enforcement state, Spring Boot live route/annotation discovery, JSON/environment configuration, native MaxMind lookup, and updated reputation behavior. Remove the old requirement for an external mmdblookup executable. Review default private-address exemptions and manifest loading.

Java 1.3 adds bounded Redis connection/socket/pool waits, fail-open/fail-closed policy, diagnostics, and state-schema compatibility guards. It supports standalone Redis and rejects Sentinel/Cluster modes. Before a rolling upgrade, test old/new instances with the intended namespace and schema. Do not bypass compatibility guards or point unrelated services at one prefix.

Review legacy model feature schema against the current six-feature pipeline; retrain or use an explicit supported importer when required. Artifacts are not generally interchangeable between languages. Spring Boot applications should use the ordered filter once, rather than adding an independent interceptor as a second enforcement layer.

Rollback and release notes

Restore compatible code, configuration, state, and model artifacts together. Avoid reverting code while leaving a newer incompatible state schema. Repeat public-client and shared-worker checks after reload.

See the upstream changelog, Python operations, Node operations, and Java operations for runtime commands.

Python 1.1.2 and Rust 0.2.2 migration

  1. Back up policy CSV files, logs, route manifests, and JSON model artifacts.
  2. Install matching Python/framework and Rust extras in the interpreter used by WSGI/ASGI; restart workers after installation.
  3. Run scripts/check_native_csv_runtime.py from the source checkout in the deployment environment.
  4. Verify allowed routes, blocked probes, external policy updates, CSV logging, and rate-cache behavior across workers. CSV rate buckets are explicit, not selected by CSV blocklist storage.
  5. Train with representative logs. CSV/gzip ingestion now streams directly; custom parsers retain their compatibility path. Reload FastAPI anomaly middleware or restart after producing a new model.

Native policy updates are atomic under filesystem locks. Keep compatible schemas in rolling upgrades; older Python writers on Windows do not provide equivalent cross-process locking. Avoid concurrent whole-file replacement. Model schemas, status mapping, timestamp semantics, and seconds/milliseconds units must remain compatible.

Redis configuration errors no longer silently select process memory in Flask. Runtime Redis rate-cache failures return generic HTTP 503 in Python. Check Redis connectivity/configuration before rollout. Native CSV rate buckets also return 503 when native support is unavailable.

Python 1.1.8 / Rust 0.2.7 migration

Release candidate: this page documents Python 1.1.8 and Rust/Python 0.2.7 in the current source checkout. Source versions do not establish registry availability. Python 1.1.8 requires aiwaf-rust>=0.2.7; framework dependencies remain extras.

Install the explicit native adapter instead of the existing AIWAF middleware chain. Installing the required Rust dependency does not automatically switch existing applications to this pipeline. Legacy adapters remain available for custom stores and hooks; their configuration and fallback behavior are separate.

  1. Back up compatible policy CSVs, request logs and trained model artifacts.
  2. Install the release candidate from the source checkout or, once published, the matching framework extra. Verify the deployed interpreter imports aiwaf_rust.NativeCSVPipeline and restart workers.
  3. Replace the existing AIWAF chain with exactly one native framework adapter. Retain application session/authentication middleware and set up adapter authentication facts.
  4. Translate supported settings into the dedicated lowercase profile. Do not copy uppercase or nested legacy dictionaries. Choose explicit rate/honeypot worker-sharing semantics.
  5. Pass a trained Rust model explicitly if inference is required. Confirm model activation; otherwise history/learning operate without model-based blocking.
  6. Verify normal routes, unknown paths, SQL/PHP rejection, method/header checks, decorator exemptions, logs, state updates and cross-worker timing. Benchmark against the same framework-only handler before rollout.

Keep the legacy adapters if you need unsupported Redis, ORM/custom stores or custom policy hooks. There is no automatic fallback from the new engine. Restore compatible configuration, code and state together on rollback; switching timing backends does not migrate timestamps.

Continue with the request lifecycle, the native profile, migration, and performance and deployment.

Migrate Node to the native engine

Native mode: Node source candidate aiwaf 1.1.4 declares aiwaf-wasm ^0.2.4. Explicit native registration validates NativeRequestPipeline at startup; missing or incompatible support is an error. There is no JavaScript policy fallback for this engine. Installing the dependency does not switch an existing legacy middleware chain.

  1. Back up legacy configuration, logs, policies and compatible model artifacts.
  2. Build/install the matching companion and use one native adapter instead of the old chain.
  3. Translate supported configuration to the lowercase profile; keep the legacy adapter for Redis, custom database stores or unsupported hooks.
  4. Install bounded parsers and route metadata before checks; supply country/authentication/route facts.
  5. Choose separate data/log files per worker and account for local counters/timing/history. Legacy state is not migrated automatically.
  6. Load a compatible Rust model explicitly, then verify allowed requests, unknown paths, nested payload rejection, model inference and logs.

Read the native lifecycle, configuration, deployment and measurements, and migration.

Shared Python policy CSV migration

Source release change: Flask, FastAPI, Django CSV mode, and the native Rust pipeline now use the same five policy CSV schemas. FastAPI CSV configuration should use storage.backend = "csv" and storage.data_dir = "/absolute/path/aiwaf_data". Use the same absolute directory for the application and CLI. Memory, JSON, database, and Django ORM modes retain their existing behavior.

  1. Stop old workers and back up state before upgrading.
  2. Startup imports runtime_store.csv in the chosen directory. The old default aiwaf_data.csv is imported into the adjoining project aiwaf_data directory.
  3. Custom legacy storage.file_path values remain accepted: /path/custom.csv maps to /path/custom/; runtime_store.csv maps to its parent. Specify data_dir to choose a different destination.
  4. Verify blocks, expiry times, exemptions, keywords, country lists, and path exemptions. Existing canonical policy wins conflicts. Original legacy sources remain intact; canonical files are backed up before import, and completion markers prevent replay after removals.
  5. Invalid legacy input fails startup. Repair it and restart to retry an incomplete import. Future writes to a completed legacy source are not imported again.

Keyword frequencies and non-policy history remain in runtime_metadata.csv. Enforcement reads blacklist.csv, whitelist.csv, keywords.csv, geo_blocked_countries.csv, and path_exemptions.csv. Restore compatible code and its original legacy state together for rollback.

Node dependency security upgrade

Update both js/package.json and its lockfile, then use npm ci. Current source tests use Jest 30, Fastify 5, and patched NestJS 11. Older broad overrides for body parsers and route-pattern parsers are removed so newer framework dependencies use compatible APIs. Test the adapter matching the application's framework after updating its own dependency tree.

The Node source version is 1.1.4; dependency changes do not imply publication. The full audit was clean on 13 October 2026. Keep development dependencies in the audit and run coverage, real WASM, and native transport checks. Native Node event stores still require a separate migration decision; Python's automatic runtime CSV import does not apply to Node.

Read the reproducible commands and validation scope.

October 2026 release upgrade

The prepared source versions are Python 1.1.6, Rust/Python 0.2.5, Node.js 1.1.4, WASM 0.2.4, and Java 1.3.4. These are source targets; verify registry availability before installing. Python requires aiwaf-rust>=0.2.5, including the TrainingEvidence API. Node offline training requires the matching WASM receipt API.

  1. Back up policies, logs, models, and training evidence. Use the same absolute data and evidence directories for application workers and CLI trainers.
  2. Install the matching native companion before upgrading its host package: Rust before Python, WASM before Node. Preserve training_evidence.json and node_training_evidence.json across expiry, unblocking, restarts, and log rotation.
  3. Stop older file writers and restart all workers on the new code. Mixing old unlocked writers with new writers can still lose updates.
  4. In staging, train twice on identical logs, then verify handled evidence does not recreate a removed or expired block. Add genuinely fresh requests and confirm they must independently satisfy the enforcement threshold.
  5. Verify that listing and expiry checks preserve concurrently refreshed blocks and unrelated IPs. Check the raw expiry and backend location if entries disappear unexpectedly.

Java CSV and file storage

Java 1.3.4 reloads current storage under a shared JVM and OS sidecar lock for each operation. Reads filter expiry without rewriting disk; mutations preserve other instances' updates and report persistence failures. This adds file I/O. Java model training still does not add blocklist entries. Rate buckets and other per-engine memory state retain their existing isolation.

Lock recovery

Python training uses an OS file lock; Java CSV/file OS locks also release on process exit. Keep their stable sidecar lock files in place while workers run. Node uses lock directories for training and legacy CSV mutations; a crash can leave them behind. Confirm the owning process has stopped before removing a Node lock directory. Do not delete training receipts to clear a lock: doing so loses handled-evidence history.

Release checks

Local validation passed 247 Node tests across 67 suites with the coverage gate, 215 Java tests with 3 skips, and 38 Rust/WASM native tests. After the native dependency bump, 11 affected Python packaging tests passed through the appropriate Django and pytest runners. These checks do not replace full release CI, dependency audits, signing, or operating-system wheel builds. Build Linux/macOS Rust wheels using the release matrix; the local bundle contains a Windows x86-64 wheel.

For release maintainers: publish the WASM companion, refresh the Node lockfile from the registry to record its actual integrity, then run npm ci and the native integration checks. Do not substitute an older native dependency to satisfy a stale packaging test. See the changelog.