intraspannet 0.1.0__tar.gz

intraspannet-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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 [yyyy] [name of copyright owner]
+
+   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.

intraspannet-0.1.0/NOTICE

@@ -0,0 +1,21 @@
+# NOTICE
+
+GDNet includes an independent implementation of a byte-level GDN encoder. The architecture follows the MambaNetBurst project:
+
+- MambaNetBurst: https://github.com/gayanku/MambaNetBurst
+- The upstream README declares the MIT license. The upstream checkout used during development did not contain a separate LICENSE file. No upstream source files are redistributed in this repository; the encoder here is a trimmed GDN-only implementation.
+
+The GDN layer is provided by flash-linear-attention:
+
+- flash-linear-attention: https://github.com/fla-org/flash-linear-attention
+- Gated Delta Networks: Improving Mamba2 with the Delta Rule, arXiv:2412.06464.
+
+Other dependencies:
+
+- PyTorch, BSD-3-Clause.
+- dpkt, BSD-3-Clause.
+- NumPy, BSD-3-Clause.
+
+Public benchmark names and numbers are cited for comparison. The datasets are not redistributed. See `docs/BENCHMARK_AUDIT.md` for the split audit and references.
+
+The model was trained on lab traffic collected by the project authors and on public benchmark training splits. No customer traffic is included.

intraspannet-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: intraspannet
+Version: 0.1.0
+Summary: Byte-level traffic classification for security product discovery
+Author: IntraSpanNet contributors
+License: Apache-2.0
+Keywords: network-security,traffic-classification,open-set-recognition,mamba,gdn
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Security
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy>=1.26
+Requires-Dist: torch>=2.4
+Requires-Dist: dpkt>=1.9
+Requires-Dist: flash-linear-attention>=0.3
+Provides-Extra: space
+Requires-Dist: gradio>=5.0; extra == "space"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# IntraSpanNet
+
+Byte-level traffic classification for security product discovery.
+
+IntraSpanNet identifies security products and services from the first five packets of a network flow. It reports the product, its type and tier, and rejects flows that do not match any known product. The released model is a four-arm ensemble with 2.86M parameters per arm.
+
+- Model: [intraspannet on Hugging Face](https://huggingface.co/luping123/IntraSpanNet)
+- Paper: [English PDF](paper/IntraSpanNet.pdf) and [Chinese PDF](paper/IntraSpanNet-zh.pdf)
+- Project page: https://lupingQAQ.github.io/IntraSpanNet/
+- Demo: not deployed. The Space code is in `space/` and requires a CUDA GPU.
+- Report: [docs/RESULTS.md](docs/RESULTS.md)
+- Benchmark audit: [docs/BENCHMARK_AUDIT.md](docs/BENCHMARK_AUDIT.md)
+
+**DOI:** [10.5281/zenodo.23643146](https://zenodo.org/records/23643146)
+
+## What it does
+
+Input: one unidirectional flow, represented as the first 5 packets, 320 bytes per packet (80 bytes of IPv4 and L4 headers, 240 bytes of payload), for a total of 1600 bytes. IPv4 source and destination addresses are zeroed.
+
+Output per flow:
+
+| Field | Meaning |
+|---|---|
+| `tier` | Security appliance, security software, or productivity software |
+| `type` | WAF, behavior management, bastion host, NDR, zero trust/VPN, EDR/HIDS, antivirus, browser, file transfer, remote administration |
+| `product` | One of 18 product labels, or `unknown` |
+| `distance` | Cosine distance to the nearest class prototype |
+| `confidence` | Mean softmax probability over the four classifier arms |
+| `topk` | Top-3 product probabilities |
+
+Unknown products are rejected when the mean prototype distance exceeds `0.1041`. The threshold was calibrated on the dev half of the validation split and was not tuned on the test half.
+
+## Results
+
+The final system uses four classifier arms, A-S0, A-LDA, B-LDA and B-S0, and the gate uses A-LDA and B-LDA. Arm naming: the letter is the pre-training run (A or B), the suffix is the training variant (`s0` standard multi-task objective, `lda` logit adjustment by class prior, `hn` hard-negative weighting). Checkpoint files carry the same labels in lower case, for example `stage3_a_s0.pth` is arm A-S0.
+
+| Metric | Test (503 flows) | All validation (1006 flows) |
+|---|---:|---:|
+| Product accuracy | 0.8787 | 0.8817 |
+| Tier accuracy | 0.9245 | 0.9334 |
+| Macro-F1 (supported classes) | 0.7621 | 0.8240 |
+| Gate AUROC | 0.9784 | 0.9820 (dev) |
+
+Additional results:
+
+- Malicious family macro-F1: 0.9702 on the deduplicated USTC-TFC2016 test set (n=1242).
+- Unknown rejection: 100% on 18 unknown-product bins. The operating point is stable from q=0.64 to q=0.75.
+- Acceptance demo: 9/10 products with the timing-rescue rule, 8/10 without it. Unknown rejection is 100%.
+- End-to-end service: 6/6 known flows. Few-shot enrollment: 8/8 after registering three sub-prototypes.
+- Throughput: 253 flows/s for the four-arm ensemble at batch 32 or higher; 1017 flows/s for a single arm. Latency at batch 1 is 43.1 ms and 10.7 ms respectively.
+- Memory: 3.4 GB peak at batch 128 on an RTX 4090; the ensemble weights total about 46 MB.
+
+The test split is a flow-level half of the validation set, not a session-level holdout. Every product class has one held-out session. This limits the strength of the absolute numbers. See [docs/RESULTS.md](docs/RESULTS.md) for the full protocol and confidence intervals.
+
+## Quick start
+
+Requirements:
+
+- Linux or Windows with an NVIDIA GPU and a working CUDA driver.
+- Python 3.10 or newer.
+- PyTorch built for your CUDA version.
+- `flash-linear-attention` and its dependencies.
+
+CPU inference is not supported in v0.1.0. The GDN backbone uses Triton kernels and requires CUDA.
+
+```bash
+git clone https://github.com/lupingQAQ/IntraSpanNet.git
+cd IntraSpanNet
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Download the weights from Hugging Face:
+
+```bash
+huggingface-cli download luping123/IntraSpanNet --local-dir weights/intraspannet
+```
+
+Classify a capture:
+
+```bash
+python -m intraspannet.cli classify \
+  --pcap sample.pcap \
+  --weights-dir weights/intraspannet \
+  --json results.json
+```
+
+The command prints a table and a summary. `--json` writes one record per flow.
+
+Example record:
+
+```json
+{
+  "product": "wazuh_agent",
+  "display": "Wazuh agent",
+  "tier": "安全软件",
+  "type": "EDR / HIDS",
+  "unknown": false,
+  "distance": 0.0104,
+  "confidence": 0.9991,
+  "class_id": 6,
+  "topk": [
+    {"product": "wazuh_agent", "display": "Wazuh agent", "probability": 0.9991},
+    {"product": "osquery", "display": "osquery", "probability": 0.0006},
+    {"product": "velociraptor", "display": "Velociraptor", "probability": 0.0002}
+  ]
+}
+```
+
+Serve the probe format over HTTP:
+
+```bash
+python -m intraspannet.cli serve --weights-dir weights/intraspannet --port 9012
+```
+
+The service accepts `POST /` with one or more 1620-byte `FLW1` records. It returns a JSON array of results.
+
+## Input format
+
+The released model uses the same format as the training pipeline:
+
+- Ethernet, IPv4, TCP or UDP.
+- One direction per flow, keyed by source address, source port, destination address, destination port, and protocol.
+- First 5 packets, in capture order.
+- Each packet contributes 80 bytes of IP and L4 headers followed by 240 bytes of payload.
+- Short packets and short flows are zero-padded.
+- IPv4 source and destination addresses are zeroed at bytes 12:20 of each flow.
+
+`pcap`, `pcapng`, and `cap` files are accepted. The preprocessor uses dpkt.
+
+## Model
+
+![Architecture](docs/assets/architecture.svg)
+
+```
+bytes (1600)
+  -> ByteEmbed (256)
+  -> [bytes, CLS] + positional embedding
+  -> 4 x GDN blocks (d_model=256, d_state=16)
+  -> CLS feature (256)
+  -> product head (18), type head (10), tier head (3), malicious head (11)
+```
+
+The open-set decision uses three sub-prototypes per class. For a flow feature `f` and prototype matrix `P`, the distance is `1 - max(cos(f, P))`. The gate averages the distance over the two gate arms.
+
+The four classifier arms share the same architecture and differ in pretraining recipe, loss weighting, and hard-negative sampling. The ensemble averages their softmax outputs and prototype distances.
+
+## Training
+
+| Stage | Data | Objective |
+|---|---|---|
+| 1. Contrastive pretraining | 33,184 training-only flows | NT-Xent / SimCLR |
+| 2. Multi-task SFT | Product, benchmark, and malicious training flows | Product, type, tier, malicious, domain-adversarial losses |
+| 3. RL fine-tuning | Training split with reward shaping | Correct product, correct type, honest rejection |
+
+Training data comes from lab captures of 18 products and services, plus public benchmark training splits. The SSL pool excludes validation and holdout flows. The validation split is divided into dev and test halves at the flow level. Selection, threshold calibration, and ensemble choice use dev only.
+
+The model was trained on 4 x RTX 4090 GPUs. The released checkpoints are the final arms.
+
+## Evaluation protocol
+
+- Product and tier accuracy: flow-level accuracy on the test half (503 flows) and on the full validation set (1006 flows).
+- Macro-F1: macro-F1 over classes with at least one test sample. Small classes make this metric unstable; the all-validation value is the more stable reference.
+- Open-set AUROC: known-product flows versus unknown and novel flows.
+- Unknown rejection: fraction of unknown-product bins rejected at the fixed threshold.
+- Malicious detection: macro-F1 on the deduplicated USTC-TFC2016 test split.
+
+The report also includes a leakage audit. Five of the six public benchmark splits contain about 80% byte-identical train/test overlap; Tor is the exception at 0%. All benchmark comparisons in the report use the same split, so relative comparisons remain same-protocol comparisons, but absolute benchmark accuracy is not evidence of generalization. The audit scripts and clean-subset lists are in the report archive.
+
+## Limitations
+
+- `stunnel` is the only product with zero recall in the acceptance demo (0/30). It needs enrollment or additional data.
+- The test split is flow-level, not session-level. Each class has one held-out session, so session-level generalization is not measured.
+- The timing-rescue rule used in the 9/10 acceptance result is not included in v0.1.0. The released ensemble alone reproduces the 8/10 raw result.
+- Mobile and IoT benchmarks are out of scope. The target scope is PCs, servers, and internal network devices.
+- The model was trained on lab traffic. Performance on production networks with different software versions, proxies, or NAT configurations is unknown.
+- CPU inference is not supported.
+- The distilled student is included for experiments. It is 5.6 percentage points below the ensemble and is not the recommended deployment.
+
+## Data and privacy
+
+The repository does not include captures. The released weights were trained on lab traffic and public benchmark training splits. No customer traffic is included. Do not upload sensitive captures to public demos.
+
+## License
+
+Code and weights: Apache-2.0. Documentation: CC-BY-4.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+## Citation
+
+```bibtex
+@software{intraspannet2026,
+  title  = {IntraSpanNet: an intranet traffic detection model for security product identification},
+  year   = {2026},
+  url    = {https://github.com/lupingQAQ/IntraSpanNet},
+  note   = {Model: https://huggingface.co/luping123/IntraSpanNet}
+}
+```
+
+## Acknowledgements
+
+The byte-level backbone follows the architecture of MambaNetBurst. The GDN layer is provided by flash-linear-attention. See [NOTICE](NOTICE) for details.

intraspannet-0.1.0/README.md

@@ -0,0 +1,202 @@
+# IntraSpanNet
+
+Byte-level traffic classification for security product discovery.
+
+IntraSpanNet identifies security products and services from the first five packets of a network flow. It reports the product, its type and tier, and rejects flows that do not match any known product. The released model is a four-arm ensemble with 2.86M parameters per arm.
+
+- Model: [intraspannet on Hugging Face](https://huggingface.co/luping123/IntraSpanNet)
+- Paper: [English PDF](paper/IntraSpanNet.pdf) and [Chinese PDF](paper/IntraSpanNet-zh.pdf)
+- Project page: https://lupingQAQ.github.io/IntraSpanNet/
+- Demo: not deployed. The Space code is in `space/` and requires a CUDA GPU.
+- Report: [docs/RESULTS.md](docs/RESULTS.md)
+- Benchmark audit: [docs/BENCHMARK_AUDIT.md](docs/BENCHMARK_AUDIT.md)
+
+**DOI:** [10.5281/zenodo.23643146](https://zenodo.org/records/23643146)
+
+## What it does
+
+Input: one unidirectional flow, represented as the first 5 packets, 320 bytes per packet (80 bytes of IPv4 and L4 headers, 240 bytes of payload), for a total of 1600 bytes. IPv4 source and destination addresses are zeroed.
+
+Output per flow:
+
+| Field | Meaning |
+|---|---|
+| `tier` | Security appliance, security software, or productivity software |
+| `type` | WAF, behavior management, bastion host, NDR, zero trust/VPN, EDR/HIDS, antivirus, browser, file transfer, remote administration |
+| `product` | One of 18 product labels, or `unknown` |
+| `distance` | Cosine distance to the nearest class prototype |
+| `confidence` | Mean softmax probability over the four classifier arms |
+| `topk` | Top-3 product probabilities |
+
+Unknown products are rejected when the mean prototype distance exceeds `0.1041`. The threshold was calibrated on the dev half of the validation split and was not tuned on the test half.
+
+## Results
+
+The final system uses four classifier arms, A-S0, A-LDA, B-LDA and B-S0, and the gate uses A-LDA and B-LDA. Arm naming: the letter is the pre-training run (A or B), the suffix is the training variant (`s0` standard multi-task objective, `lda` logit adjustment by class prior, `hn` hard-negative weighting). Checkpoint files carry the same labels in lower case, for example `stage3_a_s0.pth` is arm A-S0.
+
+| Metric | Test (503 flows) | All validation (1006 flows) |
+|---|---:|---:|
+| Product accuracy | 0.8787 | 0.8817 |
+| Tier accuracy | 0.9245 | 0.9334 |
+| Macro-F1 (supported classes) | 0.7621 | 0.8240 |
+| Gate AUROC | 0.9784 | 0.9820 (dev) |
+
+Additional results:
+
+- Malicious family macro-F1: 0.9702 on the deduplicated USTC-TFC2016 test set (n=1242).
+- Unknown rejection: 100% on 18 unknown-product bins. The operating point is stable from q=0.64 to q=0.75.
+- Acceptance demo: 9/10 products with the timing-rescue rule, 8/10 without it. Unknown rejection is 100%.
+- End-to-end service: 6/6 known flows. Few-shot enrollment: 8/8 after registering three sub-prototypes.
+- Throughput: 253 flows/s for the four-arm ensemble at batch 32 or higher; 1017 flows/s for a single arm. Latency at batch 1 is 43.1 ms and 10.7 ms respectively.
+- Memory: 3.4 GB peak at batch 128 on an RTX 4090; the ensemble weights total about 46 MB.
+
+The test split is a flow-level half of the validation set, not a session-level holdout. Every product class has one held-out session. This limits the strength of the absolute numbers. See [docs/RESULTS.md](docs/RESULTS.md) for the full protocol and confidence intervals.
+
+## Quick start
+
+Requirements:
+
+- Linux or Windows with an NVIDIA GPU and a working CUDA driver.
+- Python 3.10 or newer.
+- PyTorch built for your CUDA version.
+- `flash-linear-attention` and its dependencies.
+
+CPU inference is not supported in v0.1.0. The GDN backbone uses Triton kernels and requires CUDA.
+
+```bash
+git clone https://github.com/lupingQAQ/IntraSpanNet.git
+cd IntraSpanNet
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Download the weights from Hugging Face:
+
+```bash
+huggingface-cli download luping123/IntraSpanNet --local-dir weights/intraspannet
+```
+
+Classify a capture:
+
+```bash
+python -m intraspannet.cli classify \
+  --pcap sample.pcap \
+  --weights-dir weights/intraspannet \
+  --json results.json
+```
+
+The command prints a table and a summary. `--json` writes one record per flow.
+
+Example record:
+
+```json
+{
+  "product": "wazuh_agent",
+  "display": "Wazuh agent",
+  "tier": "安全软件",
+  "type": "EDR / HIDS",
+  "unknown": false,
+  "distance": 0.0104,
+  "confidence": 0.9991,
+  "class_id": 6,
+  "topk": [
+    {"product": "wazuh_agent", "display": "Wazuh agent", "probability": 0.9991},
+    {"product": "osquery", "display": "osquery", "probability": 0.0006},
+    {"product": "velociraptor", "display": "Velociraptor", "probability": 0.0002}
+  ]
+}
+```
+
+Serve the probe format over HTTP:
+
+```bash
+python -m intraspannet.cli serve --weights-dir weights/intraspannet --port 9012
+```
+
+The service accepts `POST /` with one or more 1620-byte `FLW1` records. It returns a JSON array of results.
+
+## Input format
+
+The released model uses the same format as the training pipeline:
+
+- Ethernet, IPv4, TCP or UDP.
+- One direction per flow, keyed by source address, source port, destination address, destination port, and protocol.
+- First 5 packets, in capture order.
+- Each packet contributes 80 bytes of IP and L4 headers followed by 240 bytes of payload.
+- Short packets and short flows are zero-padded.
+- IPv4 source and destination addresses are zeroed at bytes 12:20 of each flow.
+
+`pcap`, `pcapng`, and `cap` files are accepted. The preprocessor uses dpkt.
+
+## Model
+
+![Architecture](docs/assets/architecture.svg)
+
+```
+bytes (1600)
+  -> ByteEmbed (256)
+  -> [bytes, CLS] + positional embedding
+  -> 4 x GDN blocks (d_model=256, d_state=16)
+  -> CLS feature (256)
+  -> product head (18), type head (10), tier head (3), malicious head (11)
+```
+
+The open-set decision uses three sub-prototypes per class. For a flow feature `f` and prototype matrix `P`, the distance is `1 - max(cos(f, P))`. The gate averages the distance over the two gate arms.
+
+The four classifier arms share the same architecture and differ in pretraining recipe, loss weighting, and hard-negative sampling. The ensemble averages their softmax outputs and prototype distances.
+
+## Training
+
+| Stage | Data | Objective |
+|---|---|---|
+| 1. Contrastive pretraining | 33,184 training-only flows | NT-Xent / SimCLR |
+| 2. Multi-task SFT | Product, benchmark, and malicious training flows | Product, type, tier, malicious, domain-adversarial losses |
+| 3. RL fine-tuning | Training split with reward shaping | Correct product, correct type, honest rejection |
+
+Training data comes from lab captures of 18 products and services, plus public benchmark training splits. The SSL pool excludes validation and holdout flows. The validation split is divided into dev and test halves at the flow level. Selection, threshold calibration, and ensemble choice use dev only.
+
+The model was trained on 4 x RTX 4090 GPUs. The released checkpoints are the final arms.
+
+## Evaluation protocol
+
+- Product and tier accuracy: flow-level accuracy on the test half (503 flows) and on the full validation set (1006 flows).
+- Macro-F1: macro-F1 over classes with at least one test sample. Small classes make this metric unstable; the all-validation value is the more stable reference.
+- Open-set AUROC: known-product flows versus unknown and novel flows.
+- Unknown rejection: fraction of unknown-product bins rejected at the fixed threshold.
+- Malicious detection: macro-F1 on the deduplicated USTC-TFC2016 test split.
+
+The report also includes a leakage audit. Five of the six public benchmark splits contain about 80% byte-identical train/test overlap; Tor is the exception at 0%. All benchmark comparisons in the report use the same split, so relative comparisons remain same-protocol comparisons, but absolute benchmark accuracy is not evidence of generalization. The audit scripts and clean-subset lists are in the report archive.
+
+## Limitations
+
+- `stunnel` is the only product with zero recall in the acceptance demo (0/30). It needs enrollment or additional data.
+- The test split is flow-level, not session-level. Each class has one held-out session, so session-level generalization is not measured.
+- The timing-rescue rule used in the 9/10 acceptance result is not included in v0.1.0. The released ensemble alone reproduces the 8/10 raw result.
+- Mobile and IoT benchmarks are out of scope. The target scope is PCs, servers, and internal network devices.
+- The model was trained on lab traffic. Performance on production networks with different software versions, proxies, or NAT configurations is unknown.
+- CPU inference is not supported.
+- The distilled student is included for experiments. It is 5.6 percentage points below the ensemble and is not the recommended deployment.
+
+## Data and privacy
+
+The repository does not include captures. The released weights were trained on lab traffic and public benchmark training splits. No customer traffic is included. Do not upload sensitive captures to public demos.
+
+## License
+
+Code and weights: Apache-2.0. Documentation: CC-BY-4.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+## Citation
+
+```bibtex
+@software{intraspannet2026,
+  title  = {IntraSpanNet: an intranet traffic detection model for security product identification},
+  year   = {2026},
+  url    = {https://github.com/lupingQAQ/IntraSpanNet},
+  note   = {Model: https://huggingface.co/luping123/IntraSpanNet}
+}
+```
+
+## Acknowledgements
+
+The byte-level backbone follows the architecture of MambaNetBurst. The GDN layer is provided by flash-linear-attention. See [NOTICE](NOTICE) for details.

intraspannet-0.1.0/intraspannet/__init__.py

@@ -0,0 +1,7 @@
+"""IntraSpanNet: byte-level traffic classification for security product discovery."""
+
+from .inference import Ensemble
+from .labels import PRODUCTS, describe
+
+__version__ = "0.1.0"
+__all__ = ["Ensemble", "PRODUCTS", "describe", "__version__"]