Skip to content

Tuoni Plugin SDK version changelog

Tuoni Plugin SDK is available from Maven Central. It is recommended to always use the latest version of the SDK and to keep an eye on the changes reported on this page.

Plugin SDK versions will follow Tuoni versions, but SDK release may be skipped when there are no changes on the SDK side. Most of the time, the Plugin SDK version will be release ahead of the Tuoni release.

SDK Versions

0.10.0 (2025-05-05)

New functionality:

Jobs:

Add JobManager interface to allow plugins to create and manage jobs.
Jobs are meant to provide information to the user about long-running tasks. Jobs provide the following functionality:

  • Let user know about the status, messages and errors of the task. (See JobContext)
  • Provide info about any open ports that are used by the job
  • Optionally, provide user with ability to pause, resume or restart the task. (See Job#getSupportedActions)

In order to use Jobs, the plugin must implement the Job interface and register it using the method JobManager#registerJob

Settings:

Add SettingManager interface to allow plugins to define custom settings.
Settings are meant to make plugins customizable by the user directly from the UI.

For defining a new setting, the plugin will have to call the method SettingManager#registerSetting.
The method will return a PluginSetting object that can be used to get the value of the setting or to subscribe for changes.

The setting values are stored in the database, but the setting definition itself must be registered by the plugin on plugin initialization.
So on server restart, the plugin must register all its settings again, and the server will automatically load the values from the database.

Command Options:

Add CommandOptions type to customize behaviour when a plugin is manually starting or updating a command.
Command Options can be used for the CommandManager to customized the following:

  • sendPriority - the priority of the command in the send queue. Higher priority commands are sent before lower priority commands.
    Default: MEDIUM
  • sendDeadline - the deadline for the command to be sent. If command is not sent by the deadline, it will be marked as failed and removed from the queue.
    Default: Never expire
  • sendStatusCallback - callback to get updates about the command status. This is useful for plugins that need to know when a command is sent or failed.
    For example, relay listeners use it to correctly mark the original command as sent when the relay command is sent.
    Default: No callback
  • discardOnServerRestart - if true, the command will be discarded when the server is restarted. This is useful for commands that can not be correctly restarted.
    Default: Do not discard
  • allowSendRetries - if false, the command will not be tried to send again if initial send fails.
    This does not affect command status after the command is sent. If a command fails in agent, it is never retried.
    Default: Allow retries
FastTrack command updates:

Introduce a way for a plugin to update their own commands without any database/serialization overhead.

Added method CommandManager#updateCommandWithFastTrack to update the command with the already serialized update bytes. Bytes provided over this method will be directly queued as an update for the command.

This approach avoids the overhead of serializing the command again and allows for faster updates. It can also simplify the code for plugins that need to update their own commands (no need to implement serialize/deserialize logic for updates).

New methods:

  • CommandManager - add CommandOptions parameter to many methods
  • CommandManager - add updateCommandWithFastTrack(...) method
  • ByteArrayCommandResult - add length() method to get the length of the bytes without fetching the whole array from the database.
  • TextCommandResult - add length() method to get the length of the text without fetching the whole text from the database.
  • CommandResultEditor - add appendTextResult(...) method to append a text result to the command result without having to fetch the existing text from the database.
  • CommandContext - add CommandOptions parameter to many methods
  • CommandContext - add updateCommandWithFastTrack(...) method to update the command with the already serialized update bytes.
  • CommandTemplate - add new validateConfiguration(...) method that takes AgentInfo instead of the latest AgentMetadata object.
  • AgentInfo - add getLastCallbackTime() function
  • PluginContext - add getJobManager() and getSettingManager() methods

Deprecations:

The following methods are now marked as deprecated.
Deprecated methods will be removed in future versions.

  • CommandTemplate#validateConfiguration(AgentMetadata, Configuration)
    New method has been added: validateConfiguration(Configuration, AgentInfo).
    For 0.10.*, the old method must still be implemented, and new method is optional. In next major release, the old method will be made optional, and the new method will be required.
    Eventually the old method will be removed.
  • SendStatus#skipped() - use skipped(String) instead

0.9.0

Release skipped due to no exposed changes

0.8.0 (2025-02-14)

New functionality:

Add DiscoveredDataManager to allow plugins to store and retrieve discovered data to the database. Types of discovered data are:

  • DiscoveredHost - information about a host IP address or hostname
  • DiscoveredService - information about a service running on a port on a host
  • DiscoveredCredential - information about a credential (username, password) for a host or realm

The DiscoveredDataManager is available through the PayloadPluginContext, ListenerPluginContext, and CommandPluginContext interfaces.

New types:

  • Page - represents a page of data with items
  • Pageable - for requesting a page of data
  • Sort - for defining sorting of pageable data.
  • DiscoveredDataManager - see above for details.
  • DiscoveredHost - see above for details.
  • DiscoveredService - see above for details.
  • DiscoveredCredential - see above for details.

New methods:

  • AgentMetadata - add methods integrity(), agentType(), agentVersion(), features(), payloadId()
  • AgentMetadata.Builder - add methods integrity(String), agentType(String), agentVersion(Integer), features(List<String>), payloadId(Long)

Removals:

  • Removed type AgentInfo (deprecated in 0.6.0, moved to com.shelldot.tuoni.plugin.sdk.common package)
  • Removed type ListenerInfo (deprecated in 0.6.0, moved to com.shelldot.tuoni.plugin.sdk.common package)
  • Removed type AgentType (deprecated in 0.6.0, moved to com.shelldot.tuoni.plugin.sdk.common package)
  • Removed method AgentMetadata#os_major() (deprecated in 0.6.0)
  • Removed method AgentMetadata#os_minor() (deprecated in 0.6.0)
  • Removed method AgentMetadata.Builder#os_major(Byte) (deprecated in 0.6.0)
  • Removed method AgentMetadata.Builder#os_minor(Byte) (deprecated in 0.6.0)

Deprecations:

The following methods are now marked as deprecated. Deprecated methods will be removed in future versions.

  • FilePart#getUniqueId() - use FilePart#getFileId() instead
  • FileResource#getRelativePath() - use FileResource#getUrlPath() instead
  • FileStorage#getFile(Path) - use FileStorage#getFile(String) instead
  • CommandResultEditor#addAllFrom(CommandResultCollection) - use individual set methods instead

0.7.0 (2024-11-14)

New functionality:

Add PluginDataStore interface to allow plugins to store and retrieve key-value entries to the database. Each plugin has its own separate data store which only it can access.
Data Store supports storing and retrieving the following types: String, Long, Double, byte[], UUID.

The PluginDataStore is available through the PayloadPluginContext, ListenerPluginContext, and CommandPluginContext interfaces.

Type changes:

  • ShellcodeListener - implementations must now implement a new method getSupportedPayloadTypes() which must return a list of payload types the listener supports.
    This is necessary for server to understand whether a payload can be used with a listener or not.

New types:

  • PluginDataStore - provides functionality to store and retrieve key-value entries to/from the database.
  • PluginDataEntry - represents a key-value entry in the database.
  • DataStoreException - thrown when an error occurs while accessing the data store.

New methods:

  • PayloadInfo - add getStatus() method to get the status for payloads.
  • ListenerInfo - add getSupportedPayloadTypes() and supportsPayloadType(PayloadType) methods to get the supported payload types for listeners.
  • ListenerPluginContext - add getPluginDataStore() method.
  • PayloadPluginContext - add getPluginDataStore() method.
  • CommandPluginContext - add getPluginDataStore() method.

0.6.0 (2024-10-02)

New methods:

  • AgentMetadata - add ansiCodePage()
  • AgentMetadata.Builder - add ansiCodePage(Integer)
  • AgentInfo - add getType()

Type changes:

The following interfaces are moved to new location (previous location is still present, but deprecated):

  • AgentInfo - moves to com.shelldot.tuoni.plugin.sdk.common package
  • ListenerInfo - moves to com.shelldot.tuoni.plugin.sdk.common package
  • AgentType - moves to com.shelldot.tuoni.plugin.sdk.common package

Deprecations:

The following methods are now marked as deprecated and replaced with renamed methods.
Deprecated methods will be removed in future versions.

  • AgentMetadata#os_major() - use osMajor() instead
  • AgentMetadata#os_minor() - use osMinor() instead
  • AgentMetadata.Builder#os_major(Byte) - use osMajor(Byte) instead
  • AgentMetadata.Builder#os_minor(Byte) - use osMinor(Byte) instead

0.5.0 (2024-06-14)

🎉 First public release of Tuoni Plugin SDK 🎉

0.4.2

Released only for internal use.