adaptersentry 1.0.3__tar.gz → 2.0.0__tar.gz

adaptersentry-2.0.0/PKG-INFO

@@ -0,0 +1,467 @@
+Metadata-Version: 2.4
+Name: adaptersentry
+Version: 2.0.0
+Summary: Static security scanner for LoRA adapters — detects anomalous weight patterns in .safetensors files
+License: 
+                                         Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright 2026 Nikita Korvyakov
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+Project-URL: Homepage, https://github.com/nkorvyakov28-AS/adaptersentry-m1
+Project-URL: Documentation, https://github.com/nkorvyakov28-AS/adaptersentry-m1/tree/main/docs
+Project-URL: Repository, https://github.com/nkorvyakov28-AS/adaptersentry-m1
+Project-URL: Bug Tracker, https://github.com/nkorvyakov28-AS/adaptersentry-m1/issues
+Project-URL: Changelog, https://github.com/nkorvyakov28-AS/adaptersentry-m1/blob/main/CHANGELOG.md
+Keywords: security,llm,lora,adapter,safetensors,malware-detection,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: safetensors<1,>=0.4.0
+Requires-Dist: numpy<3,>=2.0
+Requires-Dist: scipy<2,>=1.13
+Requires-Dist: scikit-learn<2,>=1.5
+Requires-Dist: pydantic<3,>=2.5.0
+Requires-Dist: rich<16,>=13.0.0
+Provides-Extra: bench
+Requires-Dist: huggingface_hub<2,>=0.20.0; extra == "bench"
+Requires-Dist: psutil<8,>=5.9.0; extra == "bench"
+Provides-Extra: dev
+Requires-Dist: adaptersentry[bench]; extra == "dev"
+Requires-Dist: pytest<10,>=7.4.0; extra == "dev"
+Provides-Extra: ray
+Requires-Dist: ray[default]<3,>=2.9.0; extra == "ray"
+Dynamic: license-file
+
+# AdapterSentry
+
+![Python](https://img.shields.io/badge/python-%3E%3D3.11-blue)
+![License](https://img.shields.io/badge/license-Apache%202.0-blue)
+![Version](https://img.shields.io/badge/version-2.0.0-blue)
+
+AdapterSentry is a static security scanner for LoRA adapters distributed as `.safetensors`
+files. A LoRA adapter is a small file that changes how a large language model behaves; anyone
+can publish one, and a poisoned adapter can carry a backdoor that stays silent until a trigger
+appears in the input. AdapterSentry inspects the adapter's weights **before** the adapter is
+loaded, without running the model and without knowing the trigger.
+
+**v2.0.0** replaces the analysis engine: exact statistics of the effective update
+ΔW = s·B·A (no sampling, no proxies), streaming analysis that scales to 70B–405B and MoE
+models in tens of megabytes of memory, a comparison of every module with its own family inside
+the adapter, structural findings, and a new result contract (`ScanResult 2.0.0`).
+See [CHANGELOG.md](CHANGELOG.md) and [Migrating from 1.x](#migrating-from-1x).
+
+---
+
+## What it tells you
+
+```text
+$ adaptersentry scan adapter_model.safetensors
+AdapterSentry 2.0.0 · adapter_model.safetensors
+================================================================
+Verdict:  REVIEW (MEDIUM) · confidence medium · behavioural check recommended
+Status:   ok · policy default · mode full
+Why:
+  - [LOW] NO_REFERENCE_PROFILE: No calibrated reference for this model family; verdict relies on intra-adapter comparison
+  - [MEDIUM] INTRA_OUTLIER: Module departs from its family: down_proj layer 47, robust z = 9.4 (threshold 8.0, uncalibrated)
+Adapter:  peft_lora, family llama (config), 80 layers, r=64 (declared 64), α=128, scaling alpha_over_r, training trained
+Coverage: 560/560 modules analysed; 0 tensor(s) not analysed
+Intra:    max robust z 9.4 · 2 outlier module(s) · energy Gini 0.41
+Findings (1):
+  [MEDIUM] INTRA_DEPTH_SPIKE — Module departs from its family  (layer 47, down_proj)
+```
+*(Illustrative output.)*
+
+The verdict is one of **`allow`**, **`review`** or **`block`**, with the reasons, a confidence
+level and what limits it. CI gates read `verdict.action`.
+
+---
+
+## Quick start
+
+```bash
+pip install adaptersentry
+
+adaptersentry scan adapter_model.safetensors                     # text summary
+adaptersentry scan adapter_model.safetensors --format json       # ScanResult 2.0.0
+adaptersentry scan adapter_model.safetensors --format sarif \
+    --output adaptersentry.sarif --fail-on review                # GitHub code scanning + CI gate
+adaptersentry batch --input-dir adapters/ --workers 8 --fail-on review
+```
+
+```python
+from pathlib import Path
+from adaptersentry import scan
+
+result = scan(Path("adapter_model.safetensors"))
+print(result.verdict.action, result.verdict.level)
+for reason in result.verdict.reasons:
+    print(reason.code, reason.message)
+```
+
+Put `adapter_config.json` next to the `.safetensors` file (as PEFT saves it): the scan needs
+`lora_alpha` to know the real size of the update.
+
+| Option | Meaning |
+|---|---|
+| `--format text\|json\|full-json\|sarif` | output; `full-json` adds per-module features |
+| `--policy default\|strict` | `strict` blocks on structural red flags (see below) |
+| `--fail-on review\|block` | exit code 2 if the verdict reaches this action |
+| `--mode full\|fast` | `fast` uses fewer samples for the kurtosis estimate |
+| `--include-modules`, `--include-heads` | per-module / per-attention-head detail in JSON |
+| `--full-paths` | report the absolute path instead of the file name |
+
+Exit codes: `0` completed, `1` the adapter could not be analysed (the verdict is still
+`review`), `2` the `--fail-on` threshold was reached.
+
+---
+
+## How it works
+
+```
+file ─► validate ─► inventory ─► per module (streamed) ─► compare within ─► structural ─► verdict
+        header       every         exact ΔW features         each module       findings
+        & limits     tensor        via r×r cores              family
+```
+
+1. **Validate before reading.** The file must be a regular `.safetensors` file; the header
+   length, dtype, shape, byte ranges, element counts and LoRA rank are checked from the header
+   before any tensor is allocated.
+2. **Inventory.** Every tensor is classified: LoRA A/B pairs (with layer, expert and module),
+   full weights shipped via `modules_to_save`, DoRA vectors, trainable-token deltas, and
+   anything that cannot be analysed — nothing is skipped silently.
+3. **Exact features, one module at a time.** For ΔW = s·B·A, where s = α/r (or α/√r with
+   rsLoRA) comes from `adapter_config.json`, the singular values, norms and row/column norms
+   are computed exactly through the r×r matrices AAᵀ and BᵀB — ΔW itself (235 M values for a
+   70B MLP layer) is never built. Features describe the **shape** of the update, which the
+   literature finds informative, rather than its size:
+   stable rank, participation ratio, spectral entropy, concentration of the leading direction
+   versus a random baseline, entry kurtosis (estimated by importance sampling of rows so rare
+   spiky rows are not missed), and how concentrated the update is on a few output rows or
+   input columns — for `lm_head` and embeddings, on a few tokens.
+4. **Compare within the adapter.** Each module is compared with its family (all `q_proj`, all
+   `down_proj`, …): the smooth trend with depth is removed with a Theil–Sen line, then robust
+   z-scores (median/MAD) mark modules that depart from their family. This needs no reference
+   data and is insensitive to the adapter's overall strength. It runs for families of at
+   least 16 modules.
+5. **Structural findings** that numbers cannot show: complete `lm_head` / embedding / router
+   matrices shipped in the adapter, LoRA on a mixture-of-experts router, ranks that differ from
+   the declared `r` (typical of merged adapters), code/pickle/archive files next to the adapter.
+6. **Verdict** — one rule set, fail-closed:
+
+| Situation | Action |
+|---|---|
+| File could not be parsed, or part of it was not analysed | at least `review` |
+| A module departs from its family (robust z ≥ 8) | `review` |
+| Structural red flag | `review`; `block` with `--policy strict` |
+| Reference profile for the model family says p ≤ α | `review` / `block` *(reference profiles: next release)* |
+| Otherwise | `allow` |
+
+Without a calibrated reference profile the default policy never blocks: the false-positive
+rate of a block would be unknown.
+
+### Performance
+
+Measured on an 8-CPU server with a synthetic Llama-3.3-70B-shaped adapter
+(80 layers × 7 modules, r = 64, 1.66 GB bf16): `adaptersentry scan` end to end in
+**~18–20 s**, peak process memory **~160 MB** (Python and numpy included). The 1.x engine
+needed ~3.3 GB just to load the same file.
+
+---
+
+## Limits — read before relying on a verdict
+
+- **Static analysis is a first filter, not a proof.** Research on weight-space detection
+  shows strong results in the lab and clear limits: detectors trained on known attacks fail on
+  new ones, and on larger models the variation between honest adapters trained with different
+  random seeds can exceed the signal of a backdoor. A low-risk verdict is not evidence that an
+  adapter is safe; behavioural verification in an isolated environment remains necessary for
+  adapters you do not trust.
+- **Thresholds are not yet calibrated.** Intra-adapter thresholds (|z| > 3.5 outlier,
+  ≥ 8 review) were set on synthetic data. Reference profiles per model family and a measured
+  detection rate on labelled clean/poisoned adapters are the next step; until then the
+  confidence of a verdict is at most `medium`.
+- **An attacker who knows the detector** can try to spread a backdoor across many directions
+  and modules, or pad the update with inert components. Static analysis without base-model
+  information cannot fully rule this out.
+- **Not analysed:** full weight matrices (they need the base model), trainable-token deltas;
+  DoRA adapters are analysed partially. Each of these is reported and lowers the verdict's
+  confidence or raises it to `review`.
+- **Pickle-based formats** (`.bin`, `.pt`) are never deserialised. Use a dedicated
+  serialisation scanner for them.
+
+---
+
+## Output: ScanResult 2.0.0
+
+`--format json` produces one document per adapter: `scan` (who/when/how), `artifact` (hashes,
+provenance — file name only unless `--full-paths`), `adapter` (format, family, rank, α,
+scaling, modules), `status` + `coverage` (what was and was not analysed), `verdict`,
+`anomaly` (what the verdict rests on), `findings` (with exact layer/module/tensor locations),
+optional `modules`, and `errors`.
+
+- Field reference: [docs/output-schema/scan-result.md](docs/output-schema/scan-result.md)
+- JSON Schema: [docs/output-schema/scan-result-2.0.0.schema.json](docs/output-schema/scan-result-2.0.0.schema.json)
+- `adaptersentry.load_scan_result()` validates a document and rejects other major versions.
+
+---
+
+## Migrating from 1.x
+
+| 1.x | 2.0.0 |
+|---|---|
+| `analyze()`, `scan()` → `AdapterReport`, `scan_to_result()` | `scan()` → `ScanResult` |
+| `verdict.recommended_action` | `verdict.action` |
+| `overall_score`, `ensemble.score` (0–100) | removed — `verdict.level` + `anomaly` (z-scores, later p-values) |
+| `status`, `parse_status`, `analysis_mode` | `status` + `coverage` |
+| `--format summary-json` / `debug-json` | `--format json` / `full-json` |
+| `--fail-on LOW…CRITICAL` (finding severity) | `--fail-on review\|block` (verdict action) |
+| `--rank` | removed — rank is read from the tensors and checked against the config |
+| `adaptersentry-m1` command | `adaptersentry scan` |
+
+1.x results are not converted: re-scan the adapters.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/nkorvyakov28-AS/adaptersentry-m1
+cd adaptersentry-m1
+uv sync --frozen --extra dev        # or: pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+Architecture: [docs/architecture/m1-architecture.md](docs/architecture/m1-architecture.md) ·
+CLI: [docs/cli/usage.md](docs/cli/usage.md) · Batch engine:
+[docs/architecture/scan-engine.md](docs/architecture/scan-engine.md)
+
+AdapterSentry M1 is the open static-analysis layer. Planned: M2 Behavioral Sandbox — advanced
+behavioral analysis.
+
+## Background
+
+The feature design follows published work on weight-space backdoor detection in LoRA adapters,
+including *Detecting Backdoored LoRAs from Weights Alone* (arXiv:2602.15195),
+*Token-Level Generalization in LoRA Adapter Backdoors* (arXiv:2605.30189) and Z-PEFT
+(arXiv:2608.02271). Their results motivate the choices above: shape over magnitude,
+per-module and per-head features, MLP coverage, and one-class calibration instead of a
+classifier trained on known attacks.
+
+## Security
+
+See [SECURITY.md](SECURITY.md). Report a malicious adapter found in the wild with a GitHub
+issue labelled `malicious-adapter`; report vulnerabilities in AdapterSentry privately.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).