Tiresias

The Tiresias class uses the torch-train library for training and prediction. This class implements the neural network as described in the paper Tiresias: Predicting Security Events Through Deep Learning.

class tiresias.Tiresias(*args: Any, **kwargs: Any)

Implementation of Tiresias

From Tiresias: Predicting security events through deep learning by Shen et al.

Note

This is a batch_first=True implementation, hence the forward() method expect inputs of shape=(batch, seq_len, input_size).

input_size

Size of input dimension

Type

int

hidden_size

Size of hidden dimension

Type

int

output_size

Size of output dimension

Type

int

k

Number of parallel memory structures, i.e. cell states to use

Type

int

Initialization

Tiresias.__init__(input_size, hidden_size, output_size, k)

Implementation of Tiresias

Parameters

• input_size (int) – Size of input dimension

• hidden_size (int) – Size of hidden dimension

• output_size (int) – Size of output dimension

• k (int) – Number of parallel memory structures, i.e. cell states to use

Forward

As Tiresias is a Neural Network, it implements the forward() method which passes input through the entire network.

Tiresias.forward(X)

Forward data through the network

Parameters

X (torch.Tensor of shape=(n_samples, seq_len)) – Input of sequences, these will be one-hot encoded to an array of shape=(n_samples, seq_len, input_size)

Returns

result – Returns a probability distribution of the possible outputs

Return type

torch.Tensor of shape=(n_samples, size_out)

Fit

Tiresias inherits its fit method from the torch-train module. See the documentation for a complete reference.

Tiresias.fit(X, y, epochs=10, batch_size=32, learning_rate=0.01, criterion=torch.nn.NLLLoss, optimizer=torch.optim.SGD, variable=False, verbose=True, **kwargs)

Train the module with given parameters

Parameters

• X (torch.Tensor) – Tensor to train with

• y (torch.Tensor) – Target tensor

• epochs (int, default=10) – Number of epochs to train with

• batch_size (int, default=32) – Default batch size to use for training

• learning_rate (float, default=0.01) – Learning rate to use for optimizer

• criterion (nn.Loss, default=nn.NLLLoss) – Loss function to use

• optimizer (optim.Optimizer, default=optim.SGD) – Optimizer to use for training

• variable (boolean, default=False) – If True, accept inputs of variable length

• verbose (boolean, default=True) – If True, prints training progress

Returns

result – Returns self

Return type

self

Predict

The regular network gives a probability distribution over all possible output values. However, Tiresias outputs the k most likely outputs, therefore it overwrites the predict() method of the Module class from torch-train.

Tiresias.predict(X, k=1, variable=False, verbose=True)

Predict the k most likely output values

Parameters

• X (torch.Tensor of shape=(n_samples, seq_len)) – Input of sequences, these will be one-hot encoded to an array of shape=(n_samples, seq_len, input_size)

• k (int, default=1) – Number of output items to generate

• variable (boolean, default=False) – If True, predict inputs of different sequence lengths

• verbose (boolean, default=True) – If True, print output

Returns

• result (torch.Tensor of shape=(n_samples, k)) – k most likely outputs

• confidence (torch.Tensor of shape=(n_samples, k)) – Confidence levels for each output

In addition to regular prediction, Tiresias introduces online prediction. In this implementation, the network predicts outputs for given inputs and compares them to what actually occurred. If the prediction does not match the actual output event, we update the neural network before predicting the next events. This is done using the method predict_online().

Tiresias.predict_online(X, y, k=1, epochs=10, batch_size=32, learning_rate=0.0001, criterion=torch.nn.NLLLoss, optimizer=torch.optim.SGD, variable=False, verbose=True, **kwargs)

Predict samples in X and update the network only if the prediction does not match y

Parameters

• X (torch.Tensor) – Tensor to predict/train with

• y (torch.Tensor) – Target tensor

• k (int, default=1) – Number of output items to generate

• epochs (int, default=10) – Number of epochs to train with

• batch_size (int, default=32) – Default batch size to use for training

• learning_rate (float, default=0.01) – Learning rate to use for optimizer

• criterion (nn.Loss, default=nn.NLLLoss) – Loss function to use

• optimizer (optim.Optimizer, default=optim.SGD) – Optimizer to use for training

• variable (boolean, default=False) – If True, accept inputs of variable length

• verbose (boolean, default=True) – If True, prints training progress

Returns

• result (torch.Tensor of shape=(n_samples, k)) – k most likely outputs

• confidence (torch.Tensor of shape=(n_samples, k)) – Confidence levels for each output