Command-Line Interface
BitNinja has a command-line interface to alter or query your block/allow list and manage the challenge list. You can use this tool to integrate your software with BitNinja.
Installation
After installing BitNinja, bitninjacli is accessible.
Usage
bitninjacli --help
Usage: bitninjacli Command
Commands:
*****************************
* GENERAL MODULE MANAGEMENT *
*****************************
--module=<ModuleName> --reload| --stop|--start|--enable|--restart|--status|--regenerate|--show-config
--reload
Send a signal to the given module to reload configs.
--stop
Send a signal to the main process to stop the given module process.
--enabled
Send a signal to the given module to enable it. Alias of enable
--restart
Send a signal to the main process to restart the given module process.
--status
Send a signal to the given module to display its status.
--regenerate
Send a signal to the given module to regenerate configs.
Not every module has this option implemented.
--disable
Send a signal to the given module to disable it.
--show-config
Send a signal to the given module process to display its runtime loaded configurations.
--start
Send a signal to the main process to start the given module.
--enable
Send a signal to the given module to enable it.
--disabled
Send a signal to the given module to disable it. Alias of disable
************************
* IP MANAGEMENT *
************************
--whitelist|--blacklist|--greylist --add|--del|--check=ip \
[--comment="Your comment why the IP is black or whitelisted"]
You can manipulate the user specific white/black/greylist
with the corresponding command. You can add/delete/check a
given IP address.
Comments can be added to white and blacklist.
The default comment is: Operation made by cli.
example:
# bitninjacli --whitelist --add=1.2.3.4 --comment="I trust this IP"
--reloadiptables
You can reload Bitninja specific iptables rules with it.
--remove-rules
Remove every BitNinja related iptables rules and ipsets.
Use only when Agent exited abnormally.
--csflist --add|--remove; [--moduleType= WAF|SP]; --removeAll
moduleType default value: SP
Add csf rules to CSF allow/ ignore list if CSF is installed on the server
Then restarts CSF and LFD
example:
# bitninjacli --csflist --removeAll'; - removing all rules added by BitNinja from CSF
# bitninjacli --csflist --add=1.2.3.4'; - adding IP rule to siteprotection csf allow and ignore list.
# bitninjacli --csflist --add=1.2.3.4' --moduleType=WAF; - Open all ports used by the WAF module for the specified IP
# bitninjacli --csflist --add=tcp|in|d=60412|s=1.2.3.2 --moduleType=WAF'; - adding ip and port forward rule to WAFManager csf allow and ignore list.
*************************
* WAF MANAGEMENT *
*************************
--module=WAFManager --enabled|--disabled
Enable or disable the waf module locally. Only will take effect until the agent is restarted.
--module=WAFManager --status
Shows a summary of the WAF module’s status.
What redirections are made by the module and also shows information on why the redirection might be not working.
--module=SslTerminating --enabled|--disabled
You can start or stop SslTerminating manually, if Bitninja is running.
--module=SslTerminating] --reload
You can reload SslTerminating haproxy.cfg, if Bitninja is running.
--module=SslTerminating --regenerate
You can regenerate SslTerminating haproxy.cfg, if Bitninja is running.
--module=WAF --create-honeypot-url=/honeypot/folder
Add a web uri to a local Virtual honeypot uri list. This list file will
be created at /opt/bitninja-waf/etc/UserRules/user_malware_uris.data
Example use case:
You have found a web shell under public_html/uploads/images/Shell.php
With adding images/Shell.php to this list, every POST request will be
caught by the WAF, if enabled.
# bitninjacli --waf-honeypotify-uri=images/Shell.php
--module=WAFManager --generate-honeypots
Generating WAF honeypots. Config changes will be live after reload. Requires the WAf module to be reloaded to take effect.
--module=SslTerminating --add| --del-domainuri --domain=<domain> --uri=<uri>
Add URL captcha to a specified domain / uri. The setting will be deleted after agent is restarted.
--module=SslTerminating --force-recollect
Recollect the certificates
--module=SslTerminating --add-cert --domain=<domain> --certFile=<certFile> --keyFile=<keyFile> | optional --chainFile=<chainFile>
Add SSL certificate manually
--module=SslTerminating --del-cert --domain=<domain>
Delete SSL certificate manually
--module=WAFManager --generate-honeypots
Generates WAF honeypots
# bitninjacli --module=WAFManager --generate-honeypots
--module=WAFManager --enable-on-ip=<value>
Enable WAF for the given IP address even when WAF is disabled.
# bitninjacli --module=wafmanager --enable-on-ip=1.2.3.4
These rules are not permanent, restarting module or disabling it will remove them.
Extra options for enable-on-ip:
--remove
You can manually remove the rule by appending this parameter to the enf of the enable-on-ip command
--module=WAFManager --use-transparent
Switch the WAF port redirection mode to full transparent at runtime.
Not all iptables nat table rules are supported by this redirection mode. Please check the errors or module status after enabling.
These option is not permanent. Config reload or configuration modification will reset the setting
--module=WAFManager --remove-honeypots
Remove generated WAF honeypots
# bitninjacli --module=WAFManager --remove-honeypots
--module=WAFManager --no-use-ssl
Remove WAF https (ssl) port redirections at runtime.
This option is not permanent. Config reload or configuration modification will reset the state.
--module=WAFManager --use-dnat
Switch the WAF port redirection mode to DNAT at runtime.
This option is not permanent. Config reload or configuration modification will reset the state.
--module=WAFManager --use-ssl
Creates WAF https (ssl) port redirections at runtime.
These option is not permanent. Config reload or configuration modification will reset the state.
--module=wafmanager --check-redirections [--ip=<ip address>]
Check the redirections created by the WAF module on each IP address that WAF module is listening on.
With the optional --ip=<ip address > switch you can filter the output for the specified IP address
********************
* SiteProtection *
********************
--module=SiteProtection --uninstall-extension
Uninstall the SiteProtection extension from all Wordpress installations hosted on the server.
Checks if one of these control panels are installed on the server then uninstalls the corresponding plugin: Plesk, Cpanel, DirectAdmin. If there is a Wordpress based site detected on the server our version of WP-CLI, called wpninja is uninstalled.
--module=SiteProtection --install-extension
Install the SiteProtection extension in all Wordpress installations hosted on the server.
Checks if one of these control panels are is installed on the server then installs the corresponding plugin: Plesk, Cpanel, DirectAdmin. If there is a Wordpress based site detected on the server our version of WP-CLI, called wpninja is installed.
--module=SiteProtection --reinstall-extension
Uninstalls the extension and then reinstalls it
--module=SiteProtection --install-wp-plugin --domain=<value>
--module=SiteProtection --uninstall-wp-plugin --domain=<value> | --all
If the --all switch is added then the --domain switch is not required. The WP plugin will be uninstalled from all WP installations.
--module=SiteProtection --reinstall-wp-plugin --domain=<value>
**********************
* MALWARE MANAGEMENT *
**********************
--module=MalwareDetection --enabled|--disabled
You can start or stop MalwareDetection manually, if Bitninja is running.
--module=MalwareDetection --status
Shows a basic summary of the module’s status.
--module=MalwareDetection --whitelist-file=/path/to/file
Calculate the MD5 hash of the file and whitelist the hash for the malware
detector. Also upload the file content for further analysis. This function
is a user level whitelisting, so the hash will be propagated across all
servers under your user account.
--module=MalwareDetection --sandbox-file=/path/to/file
Send the file to the central BitNinja sandbox environment for analysis.
This feature is currently experimental. In the upcoming versions it will
firs quarantine the file and if the file is not malicious restores it
automatically. This feature is experimental!
--module=MalwareDetection --list-signatures
[--type=md5|hex|sa-md5|sa-snippet|ANY] default: sa-md5
[--list=black|white|ANY] default: black
[--state=draft|validating|published|ANY] default: validating
[--level=global|user|ANY] default: user
List your user level signatures.
You can filter the signatures with the different options:
--type list only a specific type of signatures. Default: no filter
--list filter blacklist or whitelist
--state filter the state of the signature
--level filter the user-level or the global signatures
--module=sandboxscanner --analyze-file=/home/path/toFile.php
--analyze-file=/home/path/toFile.php
See an analysis of the file based on structure and behaviour to check if the file might be a malware.
--module=MalwareDetection --create-signature --path=/path/to/file
[--name='Malware name'] [--non-interactive] [--recursive] [--name=<value>], [--php-only], [--type=<value>], [--force-md5], [snippet]
You can create a malware signature from a given file and share it on
all your servers with this function.
We have implemented the following lifecycle steps for malware signatures:
1. Draft - The signature is only a draft.
2. Validating - The signature is distributed to all your servers, but
it is in log only mode. This state is reserved for testing new
signatures to avoid false positives.
3. Production - The signature is actively working on your servers
4. Discarded - The signature have been removed. Files matching the discarded signature will be restored if they were quarantined.
From the CLI the signature is created in validating state, and you
can move the signature to production too. You can also use the web ui
to change the state of a signature.
This feature is an interactive step-by-step malware signature creator.
If the file contains PHP source code, it generates a Structure Analysis
signature. Otherwise it will generate an MD5 signature. Then the
signature is uploaded to the BitNinja cloud with the content of the file
and gets distributed to your servers to find matching files. Then you are
prompted to decide if the signature is production ready or not. If
you permit we move the signature to your production list, and quarantine
all matching files.
You can specify a name for the signature with the --name optional
parameter. If you don't specify a name, the file path will be the
name of the signature.
With the --non-interactive switch the program will only upload the signature
to the BN cloud, and later you can decide to accept or discard the signature
using the web security console. (admin.bitninja.io)
With the --recursive switch you can add all files under a directory
Recursively.
With the php-only switch: The file only matches PHP files based on the php detection module
Type=<value> with this switch the signature type can be set only to SA-MD5 and MD5 and Snippet accepted values: ['md5', 'sa-md5', 'sa-snippet']
The --force-md5 switch overwrites the type option and the snippet option as well.
--module=MalwareDetection --publish-signature --id=<signatureId>
Make signature published. When malware caught it will be quarantined.
--module=MalwareDetection --discard-signature --id=<signatureId>
Make signature discarded.Files matching the discarded signature will be restored if they were quarantined
--module=MalwareDetection --list-signature-catches --id=<signatureId>
List catches made by a signature.
--module=MalwareDetection --type=TYPE --similar-sa=/path/to/file
Search the index database on the server to find files with matching
structure to the specified. Useful to test new signatures.
TYPE can be either of
MD5 - Search similar MD5 files
SA-MD5 - Search in full Structure Analysis matches
SNIPPET - Search Structure Analysis snippet, a partial match
--module=MalwareDetection --restore-signature --id=<signatureId>
Restores the files that match a given signature.
--module=MalwareDetection --scan=/path/to/dir/ [--dryrun]
You can manually start MalwareDetection scan on a specific directory.
Adding the dry run switch, the module will not quarantine or clear any files.
--module=MalwareDetection --cancel
Cancel or stop a running malware scan.
Extra options for cancel
--mode=<value>
--scan-key=<value>
--module=MalwareDetection --list-scans
List all currently running malware scans.
--module=MalwareDetection --show-scan=<scanID>
See details about a currently running malware scan.
You can check which was the latest file scanned, might be useful if the scan gets stuck.
--module=MalwareDetection --reopen-signature
You can reopen a discarded signature with this command. The signature state will be draft, and you can
move it to validating state if necessary.
Extra options for reopen-signature
--id=<value>
--module=MalwareDetection --dump-sa=<value>
Dump the structure analysis internal representation of a given php file.
Usage --dump-sa=path/to/file.ph
--module=MalwareDetection --check-file=<value>
You can manually start MalwareDetection scan on a specific directory.
--module=MalwareDetection --use-auditd
Change FileSystem monitor temporary to auditd
--module=MalwareDetection --use-inotify
Change FileSystem monitor temporary to inotifywait
--webhoneypot --file=/path/ot/file
You can convert a PHP file to a honeypot.
--restore=/path/to/file
Restores file from quarantine. The path of the quarantined file is required.
Deprecated features:
module=MalwareDetection --add-file-to-signature-set=/path/to/malware \ DEPRECATED!
[--comment="Your comment why the file is malware"]
Use the new --create-signature function instead!
Add a file to your local Malware Detection's md5 signature set.
Comment will be part of the malwares name.
Eg: {MD5}User added <your_comment_goes_here>.
Default comment is path to the file added to the signature set.
--module=MalwareDetection --greylist-file=/path/to/file
Use the new --create-signature function instead!
Calculate the MD5 hash of the file and greylist the hash and upload the
file for further analysis.
****************
* DefenseRobot *
****************
-–module=DefenseRobot --collect --path=/path/to/file | --json-info=<value> | --time=<value>
Collect Defense Robot correlation information about a given file.
The file must exists and its ctime should not be older than a day
***************
* ProxyFilter *
***************
--TrustedProxy
Extra options for TrustedProxy
--add=<IPv4 or IPv6>
--del=<IPv4 or IPv6>
*************
* SenseLog *
*************
-–module=SenseLog --check-log-file=<value>
Run SenseLog log analyzes on a given log file. This command is useful when SenseLog is not activated or it haven't found the given log file yet.
Extra parameter:
--type=<ApacheAccess|NginxAccess| other ini sections found in the config.ini> Default is ApacheAccess
******************
* SandboxScanner *
******************
--module=SandboxScanner --scan=<value>
You can manually start SandboxScanner scan on a specific directory.
Extra options for scan:
--dryrun
--module=SandboxScanner --analyze-file=<value>
Runs analytics on a file and outputs the results, showing if the provided file is suspected as being malicious or not.
Example: bitninjacli --module=SandboxScanner --analyze-file=/path/to/file .
Short Version: bitninjacli --analyze-file=/path/to/file
******************
* SqlScanner *
******************
--module=SqlScanner --sqlscan [--domain=<domainName>]
Scanning SQL Databases. If a domain is provided, then only the database associated with the domain will be scanned.
--module=SqlScanner --restoreSql=<filePath>
Restores SQL record from quarantine.
--module=SqlScanner --restoreSql-signature --id=<signatureId>
Restores SQL that match a given signature.
**********
* System *
**********
--module=System --update
Runs force Agent update via cli
*******************
* Backup module *
*******************
Backup module CLI options:
--module=Backup --create-full=<value>
Create a full backup from the given directory
--module=Backup --restore=<value>
Restore backup for a directory
Extra options for restore:
--file=<value>
**********************
* MISC *
**********************
bitninjacli --licenseinfo|--serverinfo|--countusers|--version|--status-all|--dump-all-configs
--licenseinfo
Queries the current license information.
It can be trial, ok (means active pro license), no_payment
--serverinfo
Shows detailed information about the server, agent installation and license
--countusers
Counts and logs how many hosted users/domains do you have on the server.
--version
The version number of your installed BitNinja agent.
--status-all
Lists all modules (even if they are disabled) and their details in a JSON format if BitNinja is running.
--dump-all-configs
Prints all loaded configurations as a json
--stats [--minify]
Prints some statistics regarding BitNinja on the server.
Module Options
BitNinja CLI offers control over its modules with:
--module=ModuleName
Every module can receive the following commands:
--stop/--start/--restart
They will stop/start/restart BitNinja module processes. It can be useful for example, when AntiFlood module bans your attacking IP address and puts it in the local block list while you're testing the agent. In this case, you can use the following command to test further:
bitninjacli --module=AntiFlood --stop
Almost every module can receive the following commands:
--enabled/--disabled/--reload
'Enabled' will activate the module and it will start detection. 'Disabled' will stop the detection, but the module process itself will still run. With 'reload' you can reload the module configuration without the need of restarting the Agent.
Unfortunately, not every module is compatible with these command options. See the available options on the module pages.