Command-Line Interface

BitNinja has a command-line interface to alter or query your black/whitelist and manage the greylist. You can use this tool to integrate your software with BitNinja.


After installing BitNinja, bitninjacli is accessible.


bitninjacli --help

Usage: bitninjacli Command



--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 commnad. You can add/delete/check a
    given IP address.

    Comments can be add to white and blacklist.
    The default comment is: Operation made by cli.
    # bitninjacli --whitelist --add= --comment="I trust this IP"

    You can reload Bitninja specific iptables rules with it.

    Remove every BitNinja related iptables rules and ipsets.
    Use only when Agent exited abnormally.


--module=WAFManager --enabled|--disabled
    Enable or disable the waf module locally.

--module=PortHoneypot --enabled|--disabled
    Enable or disable the PortHoneypot module locally.

--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/
    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=MalwareDetection --enabled|--disabled
    You can start or stop MalwareDetection manually, if Bitninja is running.

--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

    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=MalwareDetection --create-signature --path=/path/to/file
    [--name='Malware name'] [--non-interactive] [--recursive]
    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.

    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. Othervise 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 pathn will be the
    name of the signature.

    With the --non-interactive switch the program will only uplad the signature
    to the BN cloud, and later you can decide to accept or discard the signature
    using the web security console. (

    With the --recursive switch you can add all files under a directory

--module=MalwareDetection --publish-signature  --id=<signatureId>
    Make signature published. When malware caught it will be quarantained.

--module=MalwareDetection --discard-signature  --id=<signatureId>
    Make signature discarded.

--module=MalwareDetection --list-signature-catches  --id=<signatureId>
    List catches made by a signature.

--module=MalwareDetection --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.

--module=MalwareScanner --scan=/path/to/dir/
    You can manually start MalwareDetection scan on a specific directory.

--module=MalwareScanner --cancel
    You can manually stop the running malware scan.

--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.

    Restores file from quarantine.

Deprecated features:

--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.

* MISC               *

    Queries the current license information.
    It can be free, trial, ok (means active pro license), no_payment

    Counts and logs how many users do you have on the server.

Module Options

BitNinja CLI offers control over its modules with:


Every module can receive the following commands:


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 blacklist 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’ 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.