Static Inspections

About

Static inspections are inspections that run before the server starts. These are used by Keiko to analyze your plugins' bytecode and reveal any vulnerable, unsafe, suspicious, or malicious parts before anything bad happens.

Result types

After inspecting a plugin, each of Keiko's enabled static analyses emits a list of results.

Result type	Description
clean	Keiko believes that the analyzed code is absolutely clean.
vulnerable	Keiko detected code that may be unsafe to use, or that may create vulnerabilities on your server.
suspicious	Keiko detected code that may theoretically damage your server or steal your data (if used in that way).
malicious	Keiko detected code that is usually used to damage servers or steal data.

Warnings

When Keiko finishes analysis of your plugins, it may print a list of all detected warnings. Most warnings will be non-critical — those relate to results of all types other than malicious. Critical warnings are produced by results of type malicious, and usually lead to Keiko forbidding the server to start (unless otherwise configured). If Keiko did not produce any critical warnings, but there are still warnings of other types, you will be asked whether you want the server to start anyway or not explicitly:

You need to answer "yes" or "no" in the language you use to run Keiko (that is, if you are running Keiko in Russian, you can use words "да" and "нет" instead of "yes" and "no", respectively). You can still use the "traditional" English yes and no, or their shorthands, y and n, in any locale, though. If you answer "yes", the startup will proceed. If you answer "no", Keiko will prevent the server from starting.

You can also make the process of responding to this question automatic using Keiko startup property -Dkeiko.staticInspWarnsYes=true (to always respond "yes") or ...=false (to always respond "no"). But this is not recommended: instead, you should review the warnings, and either exclude the plugins you trust, or delete the plugins that you don't.

Configuration

All static inspections' settings are placed inside config/inspections.yml. Take a look at the default configuration here.

Caching

Static inspections are slow. But scanning the same code over and over will usually (read on for details) not produce different results. For this reason, to make your server start much faster, Keiko caches all static analyses results — that is, it remembers the results from the previous server startup. Configuration changes, however, require the caches to be cleared — otherwise, they will take no effect. So make sure to clean the caches after tweaking your inspections.yml! You can do so with tool:clean.

All caches are stored inside Keiko's.artifacts folder.

Countermeasures

Countermeasures are actions that Keiko executes when facing a result of one of the types listed in the table above. You may make Keiko just warn when it detects vulnerable code, but abort server startup when it detects malware. Countermeasures are configured inside the countermeasures section of each individual static inspection. If a countermeasure is missing for some of the result types, then always ignore is inferred.

Countermeasure name	Description
always ignore	Keiko will only print a warning, but will not abort server startup. [default]
always abort	Keiko will print a warning and abort server startup.

Exclusions

If you trust a certain plugin or its part, but Keiko reports it as malicious, it is recommended to exclude this plugin (or only its trusted part(s), which is much more secure) from certain static inspections. To do so, add an appropriate filter in the exclusions list.

Filter syntax	Example	Description	Notes
FILE=<absolute path to file>	FILE={server_folder}/plugins/ProtocolLib.jar	Filters file with name ProtocolLib.jar inside your plugins/ folder.	This is usually unsafe, since other plugins' files can easily be renamed to ProtocolLib.jar as well, and thus bypass Keiko's checks.
PLUGIN=<plugin name>	PLUGIN=ProtocolLib	Filters Bukkit/Bungee plugin with name ProtocolLib (as defined in its plugin.yml).	Safer than filtering the file, but excludes too much. A plugin you trust and exclude fully may add new, malicious functionality in the future, which will bypass Keiko's checks.
SOURCE=<fully qualified class name (fqcn)>	SOURCE=my.cool.PluginName	Filters all code in class ("a big part of code") whose fully qualified name (that is, package ("folder") name + class name) is my.cool.PluginName.	Safer than the two previous types of filters, but still too broad. New, unexpected functionality may still be added inside excluded classes.
SOURCE=fqcn#methodName	SOURCE=my.cool.PluginName#onEnable	Filters code in all methods ("a small part of code") with name onEnable that belong to class whose fully qualified name is my.cool.PluginName.	Although still not ideal, this is the most "specific" and safe version. You only exclude a small trusted part of code, rather than a whole big part which may easily change.

Configuration example

  force_op:
    enabled: true
    countermeasures:
      malicious: always abort
    exclusions:
      - PLUGIN=LuckPerms

This setup means that:

• the Static.ForceOp inspection is enabled;
• when this inspection detects a malicious plugin (that is, code that most likely contains the "force-op" hack), it will print a warning and will not let the server start;
• when this inspection detects a vulnerable or suspicious plugin, it will only print a warning, but let the server start;
• Bukkit/Bungee plugin with name LuckPerms will not be analyzed by this inspection.

List of static inspections

Note: you can find more details in comments inside inspections.yml.

Inspection name	Description	Compatible with RuntimeProtect*
Static.DirectLeaks	Detects pirated versions of plugins downloaded from (patched by) DirectLeaks.	❌
Static.ForceOp	Detects plugins with the "force-op" hack — code that may give certain players the server operator (OP, admin) status under certain conditions.	✔
Static.NativesLoader	Detects code that may link native (machine) code that cannot be analyzed or monitored by Keiko.	✔
Static.SystemExit	Detects code that may cause the application (your Minecraft/Bungee server) to exit unexpectedly, without saving the current world state and plugin data properly, and thus corrupting your setup.	✔
Static.SystemProcess	Detects code that may issue system (OS) commands, for example, rm (deletes any file (Linux)).	🤔
Static.CodeInjection	Detects code that may modify itself or code that may modify other plugins' code at runtime (often viruses).	🤔
Static.PermissionsPluginsAbuse	Detects code that explicitly interacts with server permissions plugins (such as LuckPerms, PermissionsEx, or Vault). May be similar to "force-op".	❌

* details:

• ✔ there is a similar, fully-featured module in Keiko's RuntimeProtect (Keiko can fully protect you from this type of threat while your server is running);
• 🤔 there is a similar, not fully-featured module in Keiko's RuntimeProtect (Keiko can partially/usually protect you from this type of threat while your server is running);
• ❌ there is no similar module in Keiko's RuntimeProtect (Keiko cannot protect you from this type of threat at all while your server is running).