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: MEDIUMsendDeadline
- 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 expiresendStatusCallback
- 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 callbackdiscardOnServerRestart
- 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 discardallowSendRetries
- 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
- addCommandOptions
parameter to many methodsCommandManager
- addupdateCommandWithFastTrack(...)
methodByteArrayCommandResult
- addlength()
method to get the length of the bytes without fetching the whole array from the database.TextCommandResult
- addlength()
method to get the length of the text without fetching the whole text from the database.CommandResultEditor
- addappendTextResult(...)
method to append a text result to the command result without having to fetch the existing text from the database.CommandContext
- addCommandOptions
parameter to many methodsCommandContext
- addupdateCommandWithFastTrack(...)
method to update the command with the already serialized update bytes.CommandTemplate
- add newvalidateConfiguration(...)
method that takesAgentInfo
instead of the latestAgentMetadata
object.AgentInfo
- addgetLastCallbackTime()
functionPluginContext
- addgetJobManager()
andgetSettingManager()
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()
- useskipped(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 hostnameDiscoveredService
- information about a service running on a port on a hostDiscoveredCredential
- 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 itemsPageable
- for requesting a page of dataSort
- 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 methodsintegrity()
,agentType()
,agentVersion()
,features()
,payloadId()
AgentMetadata.Builder
- add methodsintegrity(String)
,agentType(String)
,agentVersion(Integer)
,features(List<String>)
,payloadId(Long)
Removals:
- Removed type
AgentInfo
(deprecated in 0.6.0, moved tocom.shelldot.tuoni.plugin.sdk.common
package) - Removed type
ListenerInfo
(deprecated in 0.6.0, moved tocom.shelldot.tuoni.plugin.sdk.common
package) - Removed type
AgentType
(deprecated in 0.6.0, moved tocom.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()
- useFilePart#getFileId()
insteadFileResource#getRelativePath()
- useFileResource#getUrlPath()
insteadFileStorage#getFile(Path)
- useFileStorage#getFile(String)
insteadCommandResultEditor#addAllFrom(CommandResultCollection)
- use individualset
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 methodgetSupportedPayloadTypes()
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
- addgetStatus()
method to get the status for payloads.ListenerInfo
- addgetSupportedPayloadTypes()
andsupportsPayloadType(PayloadType)
methods to get the supported payload types for listeners.ListenerPluginContext
- addgetPluginDataStore()
method.PayloadPluginContext
- addgetPluginDataStore()
method.CommandPluginContext
- addgetPluginDataStore()
method.
0.6.0 (2024-10-02)
New methods:
AgentMetadata
- addansiCodePage()
AgentMetadata.Builder
- addansiCodePage(Integer)
AgentInfo
- addgetType()
Type changes:
The following interfaces are moved to new location (previous location is still present, but deprecated):
AgentInfo
- moves tocom.shelldot.tuoni.plugin.sdk.common
packageListenerInfo
- moves tocom.shelldot.tuoni.plugin.sdk.common
packageAgentType
- moves tocom.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()
- useosMajor()
insteadAgentMetadata#os_minor()
- useosMinor()
insteadAgentMetadata.Builder#os_major(Byte)
- useosMajor(Byte)
insteadAgentMetadata.Builder#os_minor(Byte)
- useosMinor(Byte)
instead
0.5.0 (2024-06-14)
🎉 First public release of Tuoni Plugin SDK 🎉
0.4.2
Released only for internal use.