A method for forensic-ready intrusion detection using explainable learning, prediction-aware graph modeling, and counterfactual analysis Authors: Sghaier Guizani, Sneha Xavier, Amal Ajayan, Asem I Alalwan, Habib Hamam Published: 2026 ABSTRACT AbstractIntrusion detection pipelines often achieve strong predictive performance, yet many remain difficult to reproduce because preprocessing, model configuration, explainability integration, graph construction, and decision analysis are not documented as a unified, auditable workflow. This article presents a reproducible method for forensic-ready intrusion detection that integrates leakage-safe stratified partitioning, deterministic preprocessing, Random Forest-based multi-class prediction, explainability via SHAP and LIME, prediction-aware interaction graph construction, graph-based node and flow ranking, and counterfactual reasoning within a single executable pipeline. The method was implemented on the benchmark TON-IoT dataset, and the complete workflow was packaged with reproducible outputs and intermediate artifacts supporting verification and reuse. By combining predictive modeling, explainability, structural graph reasoning, and intervention-oriented counterfactual analysis, the proposed method provides a unified procedure for building and analyzing intrusion detection systems, with explicit control over data partitioning, feature transformation, model behavior, and forensic decision-making.• A leakage-safe intrusion detection workflow was developed using stratified train–test partitioning with strict separation of contextual identifiers from predictive features and deterministic preprocessing for reproducible model training.• A prediction-aware analytical framework was constructed by integrating SHAP and LIME-based explainability, hybrid suspicion scoring, and directed interaction graph modeling to enable graph-based ranking of suspicious nodes and flows.• Counterfactual reasoning using DiCE was incorporated to analyze decision-sensitive feature perturbations, and the complete pipeline was released with artifact-backed outputs to support reproducible forensic and cyber defense studies.Keywords: Intrusion detection, Explainable artificial intelligence, Prediction-aware graph modeling, Counterfactual reasoning, Reproducible machine learning, Forensic analytics, Randomforest, DiCE Specifications table Subject areaComputer ScienceMore specific subject areaNetwork intrusion detection, cyber-physical system security, explainable artificial intelligence, graph-based forensic analysis, reproducible machine learningName of your methodReproducible forensic-ready intrusion detection with prediction-aware interaction graph modeling, SHAP and LIME explainability, and DiCE-based counterfactual cyber defenseNot applicableCo-submission for the article Forensic-Ready Explainable AI-Based Anomaly and Intrusion Detection with Prediction-Aware Interaction Graph Modeling and Counterfactual Cyber Defense submitted to Computers and Electrical Engineering COMPELECENG-d-26–02,417Resource availabilityThe full implementation, including data preprocessing scripts, configuration of the Random Forest classifier, SHAP and LIME explainability modules, suspicion scoring logic, prediction-aware interaction graph construction, graph-based node and flow ranking, DiCE-based counterfactual reasoning, ablation evaluation, and all artifact generation routines, is publicly available [1]. The method uses the publicly available TON-IoT dataset [2], accessible from the UNSW Canberra Cyber research repository at https://research.unsw.edu.au/projects/toniot-datasets, subject to its respective access and licensing conditions. Background Intrusion detection systems (IDSs) have demonstrated strong predictive performance across benchmark datasets, yet many published workflows remain difficult to reproduce and operationally limited because preprocessing logic, classifier configuration, explainability integration, and forensic analysis procedures are insufficiently documented as a unified auditable pipeline [3]. This reproducibility gap is particularly significant in security-critical domains such as cyber-physical systems and Low-Altitude Intelligent Transportation Systems (LITS), where analytical pipelines must be verifiable, transferable, and trustworthy. A first methodological limitation concerns the treatment of data preparation and leakage control. Many intrusion detection studies apply preprocessing and encoding transformations without clearly documenting the separation between predictive features and contextual identifiers, such as source and destination IP addresses. When such identifiers are inadvertently retained in the feature matrix, the classifier may exploit entity-level memorization rather than learning generalizable traffic patterns, leading to inflated performance estimates that do not reflect true detection capability. This issue is especially important in a MethodsX contribution, where the value of the method depends not only on the reported predictive accuracy, but also on whether the entire workflow can be reproduced, audited, and trusted by other researchers. A second limitation concerns the treatment of explainability within the detection pipeline. Most existing intrusion detection frameworks either omit explainability entirely or apply it as a post-hoc feature-attribution step, disconnected from the broader analytical workflow. Global explanations derived from SHapley Additive exPlanations (SHAP) and local explanations derived from Local Interpretable Model-Agnostic Explanations (LIME) are rarely integrated into a single reproducible pipeline, and their relationship to downstream forensic reasoning is rarely explicitly documented. As a result, explanation outputs are difficult to verify independently or reuse across different experimental configurations. A third methodological gap concerns the transition from instance-level predictions to system-level forensic intelligence. Many intrusion detection pipelines terminate at predicted class labels or aggregated accuracy metrics, without translating model outputs into actionable prioritization of suspicious entities and communication flows. Graph-based analysis, suspicion scoring, and counterfactual reasoning are rarely combined within a single documented and artifact-backed workflow, limiting the operational usefulness of published methods for forensic investigation and cyber defense. To address these limitations, the present work introduces a reproducible method for forensic-ready intrusion detection that integrates five methodological components: (i) leakage-safe stratified partitioning with strict separation of contextual identifiers from predictive features; (ii) deterministic preprocessing with median imputation, one-hot encoding, and training-only pipeline fitting; (iii) hyperparameter-tuned RandomForest classification with class-balanced sampling and fixed random seeding; (iv) SHAP [4] and LIME [5] explainability integration within a unified prediction pipeline; and (v) prediction-aware interaction graph construction, graph-based node and flow ranking, and Diverse Counterfactual Explanations (DiCE) [6]-based counterfactual reasoning for intervention-oriented forensic analysis. The method is implemented on the TON-IoT dataset and packaged with classification reports, feature importance artifacts, ranked node and flow tables, ablation figures, flow concentration curves, counterfactual shift outputs, intermediate logs, and a summary report to support direct reuse and external verification. This MethodsX article emphasizes the implementation details required for reliable reproduction of the workflow, including dataset construction procedures, preprocessing retention behavior, classifier configuration and tuning, explainability computation, suspicion scoring logic, graph construction, ranking design, and artifact-backed validation. Rather than presenting the approach only as a benchmark classifier, the objective is to provide a reusable, auditable, and practically transferable procedure that other researchers can adopt and adapt for reproducible forensic-ready intrusion detection studies. Method details The proposed method was designed as a fully reproducible forensic-ready intrusion detection workflow that integrates prediction modeling, explainable artificial intelligence (XAI), graph-based reasoning, and counterfactual analysis into a unified pipeline. The workflow begins with a structured dataset representation and deterministic preprocessing, followed by leakage-safe partitioning and supervised model training. It then incorporates global and local explainability, probabilistic suspicion scoring, prediction-aware interaction graph construction, and graph-based ranking mechanisms, culminating in counterfactual analysis and artifact-backed reproducibility. At a high level, the workflow consists of the following stages: (i) dataset representation and problem formulation, (ii) deterministic data preprocessing and feature transformation, (iii) leakage-safe train–test partitioning with stratified sampling, (iv) RandomForest-based predictive modeling with hyperparameter-tuned configuration, (v) integration of SHAP and LIME explainability techniques, (vi) computation of suspicion scores using entropy and class-based risk measures, (vii) construction of a prediction-aware interaction graph using directed edge aggregation, (viii) graph-based node and flow ranking using multi-factor scoring, (ix) counterfactual reasoning using DiCE for actionable analysis, (x) experimental environment configuration with fixed software versions, and (xi) artifact-backed reproducibility through structured output generation and logging. Dataset representation and problem formulation The method was implemented using the TON-IoT dataset, which is publicly available from the UNSW Canberra Cyber research repository. The dataset consists of 211,043 network flow records with 45 attributes, including both numerical and categorical features describing network traffic behavior. The target variable is the type column, which represents a multi-class label space consisting of one normal class and multiple attack classes. The class distribution includes 50,000 samples from the normal class, approximately 20,000 samples per major attack category, and a minority class (mitm) containing 1043 samples. This class imbalance was preserved during model development and handled through stratified sampling and class-weighted learning. The dataset includes contextual identifiers, such as src_ip and dst_ip, that represent source and destination network entities. Since the original dataset lacks an explicit temporal field, a synthetic timestamp was generated using a cumulative duration strategy. Specifically, the synthetic timestamp was derived by computing the cumulative sum of the duration column and converting it to a time offset from the base time 2024–01–01 00:00:00, expressed in seconds, as follows: This timestamp was used solely for record ordering and graph construction and was not included as a predictive feature during model training. To ensure a clear separation between predictive features and contextual information, the dataset was partitioned into two groups: (i) model input features and (ii) contextual identifiers. The model input features excluded type, src_ip, dst_ip, timestamp, and the derived label column, resulting in a feature set of 40 attributes comprising 16 numerical and 24 categorical variables. The contextual identifiers were retained separately and used exclusively during graph construction to model interactions between network entities. The intrusion detection task was formulated as a supervised multi-class classification problem, with the objective of estimating class probabilities for each network flow instance. These probabilities are subsequently used for explainability analysis, suspicion score computation, and downstream graph-based reasoning within the proposed forensic-ready pipeline. Data preprocessing and feature preparation Based on the dataset representation, a deterministic preprocessing pipeline was applied to ensure data consistency, eliminate redundancy, and prepare the features for downstream model training. All preprocessing steps were implemented using Python-based data processing libraries and executed in a fixed sequence to maintain reproducibility. The preprocessing workflow began with duplicate removal. Exact duplicate rows were identified using full-row comparison and removed using pandas.DataFrame.drop_duplicates(), reducing the dataset size from 211,043 to 201,566 records. This step ensured that repeated network flow entries did not bias the learning process. Next, data cleaning was performed to handle invalid and missing values. Infinite values were first replaced with NaN. Missing values in categorical features were imputed using the constant value "unknown", while missing values in numerical features were imputed using the median of the respective feature column. Median imputation was selected for numerical variables to maintain robustness against outliers, while categorical imputation preserved feature dimensionality without introducing additional categories. After imputation, the dataset contained no remaining missing values. Feature preparation was then performed by separating predictive features from target and contextual attributes. The columns type, src_ip, dst_ip, timestamp, and the derived label column were excluded from the feature matrix. The resulting feature set comprised 40 attributes, including 16 numerical and 24 categorical features. To enable the consistent transformation of heterogeneous feature types, a ColumnTransformer pipeline was constructed. Numerical features were processed using a SimpleImputer with strategy = "median", while categorical features were processed using a pipeline consisting of SimpleImputer with strategy = "most_frequent" followed by OneHotEncoder(handle_unknown="ignore"). The encoder was configured to ignore unseen categories during inference, ensuring stability when processing new or rare values. The outputs of the numerical and categorical pipelines were concatenated using the ColumnTransformer, producing a unified transformed feature space. After one-hot encoding, the total feature dimensionality increased to 887 features. This transformation was fit on the training data and applied consistently to both the training and test sets, ensuring that the feature mappings remained identical across partitions. All preprocessing operations were performed deterministically with fixed parameters and without stochastic transformations. This ensured that repeated executions of the preprocessing pipeline on the same input dataset produced identical transformed outputs, supporting reproducibility of downstream model training and evaluation. Train-test partition and leakage control After preprocessing and feature transformation, the dataset was partitioned into training and test sets using stratified sampling to preserve the original class distribution. The split was performed using train_test_split from sklearn.model_selection with test_size = 0.30, stratify = y, and random_state = 42. This resulted in 141,096 samples in the training set and 60,470 samples in the test set. To prevent data leakage and ensure that contextual identifiers did not influence the predictive model, a strict separation was enforced between model input features and auxiliary context fields. The columns src_ip, dst_ip, and timestamp were retained exclusively for downstream graph construction and were never included in the feature matrix used for model training or inference. The feature transformation pipeline, including imputation and encoding steps, was fitted only on the training data, and subsequently applied to the test data without re-fitting. This ensured that no information from the test set influenced the learned feature representations, preserving the integrity of the evaluation. Stratified splitting ensured that minority and majority classes were proportionally represented in both the training and test sets, which was particularly important given the class imbalance, including the minority mitm class. Using a fixed random seed (random_state = 42) ensured that the same partitioning could be reproduced across multiple runs. By combining stratified sampling, strict feature-context separation, and training-only fitting of preprocessing transformations, the partitioning strategy ensured a leakage-safe experimental setup suitable for reproducible model evaluation and downstream forensic analysis. RandomForest classifier configuration The predictive component of the proposed method was implemented using a RandomForestClassifier from the sklearn.ensemble module, integrated within a preprocessing-aware pipeline. The classifier was trained on the transformed feature space generated by the ColumnTransformer described earlier, ensuring that all feature transformations were consistently applied during both training and inference. Prior to final model selection, hyperparameter optimization was conducted using RandomizedSearchCV with n_iter = 20, cv = 3, random_state = 42, and scoring = "f1_macro", resulting in 60 model fits. The search was conducted on the full training set of 141,096 samples over a predefined parameter distribution comprising: •n_estimators ∈ {100, 200, 300, 500} n_estimators ∈ {100, 200, 300, 500} •max_depth ∈ {10, 15, 20, 25, None} max_depth ∈ {10, 15, 20, 25, None} •min_samples_split ∈ {2, 5, 10, 20} min_samples_split ∈ {2, 5, 10, 20} •min_samples_leaf ∈ {1, 2, 4, 8} min_samples_leaf ∈ {1, 2, 4, 8} •max_features ∈ {"sqrt", "log2", 0.3, 0.5} max_features ∈ {"sqrt", "log2", 0.3, 0.5} •class_weight ∈ {"balanced", "balanced_subsample"} class_weight ∈ {"balanced", "balanced_subsample"} Each of the 20 randomly sampled hyperparameter combinations was evaluated using 3-fold cross-validation, with random_state = 42 ensuring reproducibility of the sampling process. The average macro F1 score across the three folds was used as the selection criterion. The configuration achieving the highest average macro F1 score was selected and subsequently used to train the final model on the complete training set. The final model was instantiated using the selected hyperparameters as follows: •n_estimators = 200. n_estimators = 200. •max_depth = None. max_depth = None. •min_samples_split = 2. min_samples_split = 2. •min_samples_leaf = 1. min_samples_leaf = 1. •max_features = 0.3. max_features = 0.3. •class_weight = "balanced_subsampl e" class_weight = "balanced_subsampl e" •n_jobs = -1 n_jobs = -1 •random_state = 42. random_state = 42. The classifier was trained on the full training dataset using the optimized configuration. The training process completed in approximately 308.55 s on a Google Colab standard CPU runtime, with parallel processing enabled by n_jobs = −1. Analysis of the trained ensemble revealed an average tree depth of 93.62, with individual tree depths ranging from 52 to 124, and an average of 3723.69 nodes per tree. These characteristics indicate that the model learned highly expressive decision boundaries that capture complex patterns in the transformed feature space. The model produces class probability estimates for each input instance, which are subsequently used for explainability analysis, suspicion score computation, and downstream graph-based reasoning. Using class_weight = "balanced_subsample" ensured that class imbalance was handled internally during training, without requiring external resampling techniques. All model training operations were performed deterministically using a fixed random seed (random_state = 42), ensuring that repeated executions of the training procedure produced identical model behavior and outputs. SHAP and LIME explainability integration To provide interpretability of model predictions at both global and local levels, the method integrates SHAP and LIME within the prediction pipeline. These techniques operate on the trained Random Forest classifier and use predicted class probabilities as the basis for explanation. Global feature importance was computed using shap.TreeExplainer, which is specifically optimized for tree-based ensemble models. SHAP values were computed on a reduced subset of three samples from the transformed test set. This subset size was adopted to maintain computational feasibility given the high-dimensional transformed feature space of 887 features, while preserving the directional reliability of global importance estimates. The total SHAP computation required approximately 19.45 s. For each evaluated instance, SHAP values were computed across all transformed features, and the mean absolute SHAP value across samples was normalized by the total sum to produce a global feature importance distribution. The SHAP analysis identified num__src_ip_bytes as the most influential feature, with a normalized importance score of 0.0941, followed by num__dst_ip_bytes (0.0933) and num__duration (0.0927). The resulting feature importance values were saved to global_feature_importance.csv and global_feature_importance.png to support downstream analysis and to provide insight into the model's decision behavior. Local interpretability was further enhanced using LIME, implemented via the lime library. LIME explanations were generated for selected individual test instances, including high-suspicion and misclassified cases identified through the forensic prediction table. For each selected instance, LIME constructed a locally faithful surrogate model by perturbing the input features and observing changes in the predicted class probabilities. The most influential features contributing to the predicted class were extracted from the surrogate model, providing instance-level interpretability complementary to the global SHAP analysis. Both SHAP and LIME explanations were computed using the same transformed feature space produced by the preprocessing pipeline, ensuring consistency between prediction and explanation stages. The integration of global and local explainability enabled the method to support both feature-level understanding of model behavior and instance-level forensic interpretation within the overall pipeline. Suspicion scoring Following the prediction and explainability stages, a quantitative suspicion-scoring mechanism was introduced to assess the likelihood that each network instance is anomalous relative to normal behavior. The suspicion score was computed using a combination of predictive uncertainty and class-based risk. Let pᵢ = [pi,1, pi,2,…, pi,C] denote the predicted class probability distribution for instance i, where C is the total number of classes. The uncertainty of the prediction was measured using Shannon entropy, defined as: In addition to uncertainty, a risk-based component was defined based on the probability of the normal class. Let pi,normal denote the predicted probability of the normal class. The risk component was computed as: The final suspicion score for each instance was defined as a weighted combination of entropy and risk: where λ is a balancing parameter controlling the relative contribution of uncertainty and risk. Equal weighting was applied with λ = 0.5, resulting in: Entropy was computed using scipy.stats.entropy applied to the predicted probability distributions, while the risk component was derived directly from the model output probabilities. The resulting suspicion scores were computed for all 60,470 test instances and used as the primary signal for downstream graph construction and ranking. This formulation captures both prediction ambiguity (high entropy) and deviation from normal behavior (low normal-class probability), providing a unified metric for identifying potentially suspicious network activity within the forensic analysis pipeline. Prediction-aware interaction graph construction To model relationships between network entities and propagate suspicion signals beyond individual instances, a prediction-aware interaction graph was constructed using the contextual identifiers preserved during preprocessing. The graph was implemented as a directed graph using the networkx.DiGraph structure. In this formulation, each unique network entity, identified by IP address, was represented as a graph node. Directed edges were established between nodes based on observed network flows, where each edge (u, v) corresponds to a communication from source IP u to destination IP v. The contextual fields src_ip and dst_ip were used exclusively for this purpose and were not involved in model training. Each edge was associated with aggregated interaction statistics derived from the suspicion scores computed in the previous step. Specifically, for each observed interaction between nodes u and v, the following quantities were accumulated: •count: total number of interactions between u and v. count: total number of interactions between u and v. •suspicion_sum: cumulative sum of suspicion scores across all interactions. suspicion_sum: cumulative sum of suspicion scores across all interactions. From these aggregated values, an average suspicion score for each edge was computed as: This formulation ensures numerical stability by preventing division by zero when interactions are sparse. The resulting graph captured both the network's structural connectivity and the distribution of suspicious activity across interactions. In the realized dataset, the constructed graph contained 505 nodes and 667 directed edges, reflecting the interaction patterns present in the test partition of the network traffic. By incorporating suspicion scores into edge attributes, the graph becomes prediction-aware, enabling downstream analysis to consider not only the existence of connections but also their associated risk levels. This graph representation serves as the foundation for subsequent node and flow ranking operations in the proposed forensic analysis pipeline. Graph-based node and flow ranking After constructing the prediction-aware interaction graph, a ranking mechanism was applied to identify the most suspicious nodes and flows in the network. The ranking process combines the graph's structural properties with aggregated suspicion signals to produce a unified risk score for each node. First, a global importance measure was computed using the PageRank algorithm implemented in networkx.pagerank with damping factor αPR = 0.85. PageRank captures the relative importance of nodes based on the structure of incoming connections and the propagation of their influence through the network. For each node v, the following quantities were computed: •Outgoing suspicion Sout(v): sum of average suspicion scores over all outgoing edges. Outgoing suspicion Sout(v): sum of average suspicion scores over all outgoing edges. •Incoming suspicion Sin(v): sum of average suspicion scores over all incoming edges. Incoming suspicion Sin(v): sum of average suspicion scores over all incoming edges. •Degree deg(v): total number of incoming and outgoing edges. Degree deg(v): total number of incoming and outgoing edges. •PageRank score PR(v): global structural importance of the node. PageRank score PR(v): global structural importance of the node. A composite risk score was then defined for each node as a weighted combination of these components: where the weighting coefficients were set to α = 0.4, β = 0.3, γ = 0.2, and δ = 0.1. The weighting scheme assigns the highest contribution to outgoing suspicion (α = 0.4) because initiating suspicious communications is a stronger indicator of malicious behavior than receiving them. Incoming suspicion receives a moderate weight (β = 0.3) to capture nodes that are targeted by suspicious sources. PageRank contributes a structural centrality signal (γ = 0.2) to identify globally influential nodes, while node degree (δ = 0.1) provides a lightweight connectivity measure that does not dominate the behavioral signals. The weights were fixed and applied uniformly across all nodes, ensuring consistent scoring across the graph. Nodes were ranked in descending order of R(v), and the top 20 nodes were extracted and saved to top_suspicious_nodes.csv for further forensic analysis. In addition to node ranking, flow-level ranking was performed using the average suspicion scores associated with graph edges. Edges were sorted in descending order of suspicion_avg to identify the most suspicious communication flows between entities, and the results were saved to top_suspicious_flows.csv. This ranking mechanism enables prioritizing network entities and interactions for further investigation, transforming the graph representation into an actionable forensic analysis tool within the proposed pipeline. DiCE-based counterfactual reasoning To provide actionable insights into model predictions and support forensic analysis, counterfactual explanations were generated using the DiCE framework implemented via the dice-ml library. Counterfactual reasoning enables the identification of minimal feature changes required to alter the predicted class of a given instance. The query instance for counterfactual analysis was selected as the test set sample with the highest risk_vs_normal score among all instances predicted as non-normal, ensuring that the counterfactual analysis targeted the most forensically relevant case. In the realized run, this query instance was predicted as ransomware, and the desired target class was set to normal. The DiCE framework was configured using the following parameters: •method = "random". method = "random". •total_CFs = 1. total_CFs = 1. •desired_class = normal (class index 5). desired_class = normal (class index 5). •features_to_vary = "all". features_to_vary = "all". Counterfactual generation was restricted to the 16 continuous numerical features in the dataset. Categorical features were not perturbed during this process to maintain the semantic consistency of the generated instances. The DiCE data object was constructed using the training set with the sklearn backend, and the trained pipeline model was passed directly as the prediction model. For the selected query instance, DiCE successfully generated a valid counterfactual example by minimally altering continuous feature values to shift the prediction from ransomware to the normal class. The counterfactual generation process completed in approximately 2.60 s. The resulting counterfactual explanations were used to analyze which feature changes contributed most significantly to altering the model's decision. These outputs provide actionable insights into the conditions under which suspicious network behavior could be reclassified as normal, supporting both interpretability and potential defensive strategies. All counterfactual outputs were saved as pipeline artifacts, including probability shift visualizations (counterfactual_shift.png) and structured experiment logs, ensuring reproducibility and traceability of the analysis. Experimental environment All experiments were implemented in Python and executed in a notebook-based environment compatible with both local systems and Google Colab. The implementation was designed to be portable across execution platforms while maintaining consistent behavior through fixed software configurations. The reported pipeline run was executed on a Google Colab standard CPU runtime. Training of the Random Forest classifier completed in approximately 308.55 s under this configuration, with parallel processing enabled via n_jobs = −1. The reported pipeline was executed using Python version 3.12.13. The core libraries used in the implementation, along with their respective versions, are listed below: •numpy 2.0.2. numpy 2.0.2. •pandas 2.2.2. pandas 2.2.2. •scikit-learn 1.6.1. scikit-learn 1.6.1. •shap 0.51.0. shap 0.51.0. •lime 0.2.0.1. lime 0.2.0.1. •dice-ml 0.12. dice-ml 0.12. •networkx 3.6.1. networkx 3.6.1. •scipy 1.16.3. scipy 1.16.3. •matplotlib 3.10.0. matplotlib 3.10.0. To ensure reproducibility, all stochastic components in the pipeline were controlled using fixed random seeds, including random_state = 42 for data splitting and model training. Library versions were recorded automatically at runtime and saved to library_versions.json to support auditability and rerun consistency. The codebase was structured to produce consistent outputs across different environments, provided that the specified library versions are maintained. Artifact-backed reproducibility To ensure the practical reproducibility and auditability of the proposed method, the entire pipeline was designed to generate structured artifacts at each stage of execution. These artifacts include tabular outputs, visualizations, intermediate logs, and summary reports, enabling external validation and reuse of the method without reliance on implicit state or undocumented steps. The pipeline produces a set of final output files organized into tables, figures, and reports. Tabular outputs include per-class classification reports (classification_report.csv, classification_report.xlsx), confusion matrix tables (confusion_matrix_table.csv), global feature importance scores (global_feature_importance.csv), and ranked outputs such as top_suspicious_nodes.csv and top_suspicious_flows.csv. These files provide structured summaries of model performance and graph-based analysis results. Visual artifacts are generated to support the method's interpretability and validation. These include confusion matrix visualizations (confusion_matrix.png), global feature importance plots (global_feature_importance.png), ablation study curves for Precision@k and Recall/MRR (ablation_precision_at_k.png, ablation_recall_mrr.png), suspicious flow concentration curves (flow_concentration.png), and counterfactual probability shift plots (counterfactual_shift.png). In addition to final outputs, intermediate artifacts are generated to capture the pipeline's internal state. These include experiment-level logs (experiment_log.csv), structured results (experiment_results.json), summary statistics (experiment_summary_stats.json), and a library version record (library_versions.json). These files record key metrics, configuration parameters, and execution traces, supporting reproducibility and debugging. A summary report is also generated in plain text format (summary_report.txt), providing a consolidated overview of the pipeline execution and key findings. All artifacts are saved in a structured directory hierarchy under the base directory Forensic_Ready_XAI_IDS to maintain organization and facilitate retrieval. The complete implementation of the method, including code, configuration, and execution instructions, is made publicly available in the GitHub repository. The codebase is compatible with both local environments and Google Colab, enabling users to reproduce results by running the provided notebook with the specified environment configuration. By combining deterministic processing, fixed configurations, comprehensive artifact generation, and public code availability, the method ensures reproducibility not only at the conceptual level but also at the practical implementation level. Method validation Preprocessing realization and dataset composition The first validation step was to confirm that the deterministic preprocessing workflow produced a consistent, non-empty, and audit-ready dataset suitable for supervised training and downstream forensic analysis. This verification is important because the proposed method depends not only on classifier performance, but also on whether the full data-construction procedure can be reproduced without silent data loss, identifier leakage, or encoding inconsistencies. Duplicate removal reduced the raw dataset from 211,043 to 201,566 records, eliminating 9477 exact duplicate rows. Following deduplication, infinite-value replacement, and column-type-aware imputation, the dataset contained no remaining missing values. These outcomes confirm that the cleaning pipeline operated as intended and that all downstream operations received a complete and consistent input. Feature preparation correctly excluded the label column type, the contextual identifier columns src_ip, dst_ip, and timestamp, and the derived label column from the predictive feature matrix. The resulting raw feature space comprised 40 attributes, consisting of 16 numerical and 24 categorical variables. After application of the ColumnTransformer pipeline, the transformed feature dimensionality expanded to 887 features, confirming that the one-hot encoding of categorical variables was applied correctly and that the output space was consistent with the configured preprocessing design. Stratified partitioning produced a training set of 141,096 samples and a test set of 60,470 samples, corresponding to a 70/30 split. The use of stratify = y and random_state = 42 ensured that class proportions were preserved across both partitions, including the minority mitm class. This confirmed that the leakage-safe partitioning procedure operated correctly and that contextual identifiers were successfully excluded from the predictive feature matrix prior to splitting. The preprocessing stage also generated a structured experiment registry, saved in experiment_results.json, that records the dataset shape, label distribution, identifier availability, cleaning statistics, and feature preparation outcomes. These retained records allow the complete realized dataset structure to be verified independently of the training code, treating preprocessing validation as a reproducible component of the method rather than an informal sanity check. Hyperparameter selection and classifier training The second validation step was to confirm that the hyperparameter optimization and classifier training procedures produced a stable, well-configured model consistent with the documented settings. Hyperparameter optimization via RandomizedSearchCV with n_iter = 20, cv = 3, and random_state = 42, scoring = "f1_macro" was conducted on the full training set of 141,096 samples, resulting in 60 total model fits. The best-performing configuration identified through this search was subsequently used to instantiate the final classifier with n_estimators = 200, max_depth = None, max_features = 0.3, and class_weight = "balanced_subsample", among other fixed parameters. Using macro F1 as the optimization criterion ensured that the search prioritized balanced performance across all attack categories rather than optimizing for the dominant class. The final classifier was trained on the complete training set and completed in 308.55 s on a Google Colab standard CPU runtime. Analysis of the trained ensemble confirmed that 200 decision trees were constructed, with an average tree depth of 93.62, individual tree depths ranging from 52 to 124, and an average of 3723.69 nodes per tree. The training accuracy reached 0.9999, indicating that the model effectively fit the training data. This result was expected given the absence of a maximum depth constraint and the large ensemble size, and was evaluated in the context of test set performance to assess generalization. All training parameters were stored in the experiment registry under the model key, including hyperparameter values, tree-level diagnostics, training accuracy, and training time. These retained records confirm that the training stage was executed as specified and provide a machine-readable audit trail linking the final model to its configuration. Predictive performance validation The third validation step was to assess whether the trained classifier achieved reliable multi-class predictive performance on the held-out test set. Evaluation was performed using the full test partition of 60,470 samples across all ten traffic classes. The classifier achieved an overall test accuracy of 0.9890, a macro precision of 0.9642, a macro recall of 0.9740, a macro F1 score of 0.9687, and a macro one-vs-rest ROC-AUC of 0.9979. These results indicate strong and consistent discrimination across all attack categories and demonstrate that the trained model generalizes effectively to unseen test data. Table 1 summarizes the per-class performance. Near-perfect classification was achieved for well-separated attack categories, including backdoor, normal, and ransomware, with F1 scores of 1 for each. Strong performance was also observed for password (F1 = 0.995), scanning (F1 = 0.990), ddos and dos (F1 = 0.985 each), and injection and xss (F1 = 0.975 each). The lowest per-class F1 score was observed for the mitm class (F1 = 0.780), which is consistent with its minority status in the dataset (1043 samples) and its known behavioral overlap with normal traffic patterns. Table 1Per-class classification performance on the held-out test set.Table 1 dummy alt textClassPrecisionRecallF1SupportBackdoor1.0001.0001.0006000Ddos0.9900.9800.9856000Dos0.9900.9800.9856000Injection0.9800.9700.9755998Mitm0.7300.8400.780313Normal1.0001.0001.00013,738Password1.0000.9900.9956000Ransomware1.0001.0001.0004421Scanning0.9900.9900.9906000Xss0.9700.9800.9756000Macro avg0.9640.9740.96960,470 Per-class classification performance on the held-out test set. The confusion matrix confirmed a strongly diagonal structure, as shown in Fig. 1, with the majority of misclassifications concentrated among semantically related attack categories. The mitm class showed occasional overlap with normal traffic, while injection and xss exhibited partial confusion due to their shared application-layer characteristics. This error structure indicates that the classifier learned meaningful behavioral boundaries rather than memorizing superficial statistical artifacts. Per-class results were saved to classification_report.csv and classification_report.xlsx, and the confusion matrix was saved to confusion_matrix_table.csv and confusion_matrix.png. Confusion matrix of the Random Forest classifier on the held-out test set. The strongly diagonal structure indicates high classification accuracy, with most errors concentrated among semantically related attack categories. Explainability validation The fourth validation step confirmed that the SHAP and LIME explainability modules produced interpretable and operationally plausible feature importance outputs consistent with known network traffic semantics. Global feature importance was computed using shap.TreeExplainer on three samples from the transformed test set, completing in 19.45 s, as shown in Fig. 2. The top-ranked features identified by SHAP were num_src_ip_bytes (normalized importance 0.0941), num_dst_ip_bytes (0.0933), num_duration (0.0927), cat_service_http (0.0873), and num_dst_port (0.0805). These features correspond to traffic volume, connection duration, service type, and port activity, which are established indicators of anomalous network behavior in the intrusion detection literature. The alignment between SHAP-identified features and domain-relevant traffic characteristics provides evidence that the model relies on meaningful signals rather than opaque statistical correlations. Global feature importance derived from SHAP values. The ranking highlights traffic volume, duration, service type, and port-related features as dominant contributors to model predictions. Local LIME explanations were generated for selected high-suspicion and misclassified instances, providing instance-level interpretability complementary to the global SHAP analysis. The LIME surrogate models identified feature contributions consistent with the global importance ranking, reinforcing confidence in the directional validity of both explanation methods. Global importance results were saved to global_feature_importance.csv and global_feature_importance.png to support external inspection and reuse. Graph construction and ranking validation The fifth validation step confirmed that the prediction-aware interaction graph was correctly constructed and that the node and flow ranking mechanism produced interpretable, actionable prioritization outputs. Graph construction from the test partition produced a directed graph containing 505 nodes and 667 edges, confirming that the src_ip and dst_ip contextual identifiers were successfully mapped to graph entities, and the edge aggregation of suspicion scores operated as specified. The presence of 505 unique communicating entities and 667 directed interactions across the 60,470 test instances confirms that the graph captured a meaningful subset of network communication structure rather than producing a degenerate or fully disconnected topology. Node ranking using the composite risk score R(v)=0.4·Sout(v)+0.3·Sin(v)+0.2·PR(v)+0.1·deg(v) identified 192.168.1.31 as the highest-risk node, with a risk score of 28.49, followed by 192.168.1.30 (23.68) and 192.168.1.34 (22.97). The top-ranked nodes exhibited high outgoing suspicion values, consistent with the interpretation that initiating suspicious communications is a primary indicator of malicious activity. The ablation study confirmed that the full graph-aware model outperformed reduced variants across Precision@k metrics, as shown in Fig. 3, including out-degree-only, in-degree-only, and no-graph baseline configurations, across Precision@3, Precision@5, Precision@10, Recall@10, and MRR, as shown in Fig. 4, validating the contribution of the multi-factor ranking design. Ablation results were saved to ablation_precision_at_k.png and ablation_recall_mrr.png. Ablation study results showing Precision@k for different model variants. The full graph-aware model consistently outperforms reduced configurations, demonstrating the contribution of graph-based reasoning. Ablation study results showing Recall@10 and Mean Reciprocal Rank (MRR). The full model achieves superior ranking performance compared to reduced variants. The suspicious-flow concentration analysis showed a strongly skewed cumulative distribution, as illustrated in Fig. 5, confirming that a small subset of high-ranked flows accounts for a disproportionately large share of total suspicious activity. This heavy-tailed concentration supports the operational usefulness of the flow ranking for focused forensic triage. The concentration curve was saved to flow_concentration.png. Cumulative suspicious-flow concentration curve. A small subset of flows accounts for a disproportionate share of total suspicious activity, supporting prioritized forensic investigation. Counterfactual reasoning validation The sixth validation step confirmed that the DiCE-based counterfactual reasoning module successfully generated a valid counterfactual instance for the most suspicious non-normal test case. The query instance was selected as the test sample with the highest risk_vs_normal score among all non-normal predictions, which in the realized run corresponded to an instance predicted as ransomware. DiCE was configured with method = "random", total_CFs = 1, desired_class = normal, and features_to_vary = "all", operating on the 16 continuous numerical features. The counterfactual generation completed successfully in approximately 2.60 s, producing a valid instance whose predicted class shifted from ransomware to normal. The resulting probability shift confirmed that selected continuous features have a measurable influence on the model's classification boundary, as illustrated in Fig. 6, and that directional intervention reasoning is feasible within the proposed pipeline. The counterfactual output was saved to counterfactual_shift.png and logged in the structured experiment registry, ensuring traceability of the analysis. Counterfactual probability shifts for the selected high-suspicion instance. The figure illustrates the change in predicted class probabilities before and after feature perturbation, demonstrating the transition from an attack class (ransomware) to the normal class. Runtime behavior and artifact-backed reproducibility The final validation step assessed the completeness of the retained artifact package and confirmed that the pipeline produced a fully auditable, externally reproducible result set. The end-to-end pipeline execution was completed on a Google Colab standard CPU runtime. The dominant computational cost was Random Forest training at 308.55 s, followed by SHAP computation at 19.45 s and DiCE counterfactual generation at approximately 2.60 s. These runtimes confirm that the pipeline can be executed within standard Colab session limits without requiring specialized hardware or GPU acceleration. The complete retained artifact package includes per-class classification reports (classification_report.csv, classification_report.xlsx), confusion matrix outputs (confusion_matrix_table.csv, confusion_matrix.png), global feature importance tables and figures (global_feature_importance.csv, global_feature_importance.png), ranked node and flow tables (top_suspicious_nodes.csv, top_suspicious_flows.csv), ablation figures (ablation_precision_at_k.png, ablation_recall_mrr.png), flow concentration curve (flow_concentration.png), counterfactual shift figure (counterfactual_shift.png), intermediate logs (experiment_log.csv, experiment_results.json, experiment_summary_stats.json), library version record (library_versions.json), and a plain-text summary report (summary_report.txt). This artifact-backed packaging is one of the principal methodological strengths of the workflow. Rather than reporting only a final score, the method preserves the intermediate evidence needed to reconstruct how that score was obtained, which is precisely the level of procedural transparency that a MethodsX article is intended to support. Limitations Although the proposed method improves reproducibility, leakage control, explainability integration, and forensic prioritization, several limitations should be acknowledged. First, the evaluation is conducted on a single benchmark dataset, the TON-IoT dataset, rather than across multiple intrusion detection benchmarks. While this dataset provides a diverse multi-class label space covering ten traffic categories, the reported performance should not be interpreted as evidence of guaranteed generalization to all network environments, attack families, or real-world deployment conditions without further external validation. Second, the SHAP global importance computation was performed on a reduced subset of 3 samples from the transformed test set to maintain computational feasibility within the Colab CPU environment. While this approach preserves the directional reliability of feature importance estimates, it does not produce a full-dataset SHAP analysis. Researchers with access to more powerful computational resources may extend the SHAP evaluation to a larger sample for more precise global attribution estimates. Third, the prediction-aware interaction graph is constructed from aggregated IP-level interactions rather than from richer sequential event traces or temporal graph structures. While this design is computationally efficient and stable, it does not explicitly model the temporal ordering of attack progression or the evolution of communication patterns. Extension to fully temporal graph formulations would strengthen the framework's ability to capture coordinated or multi-stage threats. Fourth, the graph-based node ranking relies on fixed weighting coefficients (α = 0.4, β = 0.3, γ = 0.2, δ = 0.1) that were set based on domain reasoning rather than learned from data. These weights may require adaptation across different operational contexts or network environments where the relative importance of outgoing activity, incoming exposure, structural centrality, and degree differ from the assumptions embedded in the current formulation. Fifth, the DiCE counterfactual module was applied to a single high-suspicion query instance using the random search method with total_CFs = 1. This configuration supports directional actionability and sensitivity analysis but does not guarantee minimal, diverse, or operationally feasible feature changes. More advanced counterfactual optimization strategies and multi-instance analysis could be applied in future extensions to produce richer and more practically actionable outputs. Finally, the synthetic timestamp generated from cumulative flow duration was used solely to support graph construction ordering and was not validated against real network event timestamps. In deployments where accurate temporal information is available, replacing the synthetic timestamp with real event times would improve the fidelity of the temporal graph representation and strengthen the framework's support for time-aware forensic analysis. Ethics statements Not Applicable Acknowledgments The authors gratefully acknowledge the financial support provided by Uni de Moncton and Alfaisal University. They also acknowledge the in-kind support and institutional resources provided by the University of Johannesburg and IITG, which contributed to the successful completion of this work. Declaration of competing interest The authors declare that they have no known competing financial interests or personal relationships that could have appeared to influence the work reported in this paper. Contributor Information Sghaier Guizani, Email: sguizani@alfaisal.edu. Amal Ajayan, Email: a_amal@cb.students.amrita.edu. Data availability GitHub repository link is provided in the manuscript. References Associated Data Data Availability Statement GitHub repository link is provided in the manuscript.