google/tsunami-security-scanner-callback-server

Tsunami Callback Server

Introduction

Tsunami Callback Server is a network service that Tsunami uses to help discover blind vulnerabilities such as server-side request forgery (SSRF) and blind RCE.

Design

Tsunami callback server is a standalone application that can receive both http requests and DNS queries. A tsunami plugin can now check against the callback server to see if there are any out-of-bound interactions triggered from the detection stage.

Internally, to identify interactions per plugin, tsunami payload generator generates a unique id and returns the hash (SHA3 one-way hash by default) of the id with a callback server address for plugin to use and the callback server logs the hashed id from incoming requests. At the end of the detection, TcsClient queries the callback server about the original unhashed id. Callback server then applies the same hash on the id, and returns logged interactions if they exist.

Run Tsunami Scanner with Callback Server

Running Callback Server Locally

HTTP callback

Clone the repository and build the jar file.

git clone https://github.com/google/tsunami-security-scanner-callback-server
cd tsunami-security-scanner-callback-server/
./gradlew shadowJar

Start callback server

• With default settings:

java -cp "main/build/libs/tcs-main-[version]-cli.jar"  com.google.tsunami.callbackserver.main.TcsMain

• With the example config file:

java \
    -cp "main/build/libs/tcs-main-0.0.1-SNAPSHOT-cli.jar" \
    com.google.tsunami.callbackserver.main.TcsMain \
    --custom-config=tcs_config.yaml

Configure Tsunami scan to use the local callback server by adding the followings to the Tsunami config file:

plugin:
  callbackserver:
    callback_address: "127.0.0.1"  # Running callback server locally
    callback_port: 8881            # Make sure to match with ones configured in tcs_config.yaml
    polling_uri: "http://127.0.0.1:8880"

Then run Tsunami following the instructions here using the modified tsunami.yaml file.

DNS Callback

⚠️ Testing DNS callback locally requires modifying your iptables to reroute DNS queries to the port that callback DNS server is running at. You won't be able to resolve other domains once the iptables are updated.

Update the callback server config file to also spin up a DNS server:

common:
  domain: cb.tsunami
  external_ip: 127.0.0.1
storage:
  in_memory:
    interaction_ttl_secs: 43200  # 12 hours
    cleanup_interval_secs: 3600  # 1 hour
recording:
  http:
    port: 8881
    worker_pool_size: 2
  dns:                           # Config for DNS server
    port: 8883                   # Port to reroute DNS query to
    worker_pool_size: 2
polling:
  port: 8880
  worker_pool_size: 2

Start the callback server as before, now you should see a DNS server turned up as well.

Create 2 new rules in your local iptables to reroute DNS queries to the port where your own DNS server is running at:

sudo iptables -t nat -A OUTPUT -p udp --dport 53 -j DNAT --to-destination 127.0.0.1:8883
sudo iptables -t nat -A OUTPUT -p tcp --dport 53 -j DNAT --to-destination 127.0.0.1:8883

Now if you try to resolve the custom domain you set up with dig cb.tsunami, it should resolve to 127.0.0.1.

Update callback_address field in the Tsunami config file to your custom domain to be used by tsunami payload generator.

Then run a Tsunami scan as before, now the payload generator will generate all the tsunami callback payloads using the configured domain, which will send DNS queries to the local DNS server you set up.

Don't forget to remove these iptables rules once you are done, otherwise you won't be able to resolve any other domain names properly.

sudo iptables -t nat -D OUTPUT -p udp --dport 53 -j DNAT --to-destination 127.0.0.1:8883
sudo iptables -t nat -D OUTPUT -p tcp --dport 53 -j DNAT --to-destination 127.0.0.1:8883

Contributing

Read how to contribute to Tsunami.

License

Tsunami CallbackServer is released under the Apache 2.0 license.

Copyright 2022 Google LLC.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Disclaimers

Tsunami is not an official Google product.

tsunami-security-scanner-callback-server's Issues

Gradle Compilation Error

Hi. My current environment is Java 11 and Ubuntu 22.04. I can run Tsunami security scanner without any problem. However, when I try to build jar file from this repository to run callback server, I encounter with the following error:

ivar@ivar-virtual-machine:~/tsunami-security-scanner-callback-server$ ./gradlew shadowJar

> Task :tcs-storage:compileJava FAILED
/home/ivar/tsunami-security-scanner-callback-server/storage/src/main/java/com/google/tsunami/callbackserver/storage/RedisInteractionStore.java:22: error: cannot find symbol
import com.google.common.annotations.VisibleForTesting.Visibility;
                                                      ^
  symbol:   class Visibility
  location: @interface VisibleForTesting
/home/ivar/tsunami-security-scanner-callback-server/storage/src/main/java/com/google/tsunami/callbackserver/storage/RedisInteractionStore.java:47: error: cannot find symbol
  @VisibleForTesting(productionVisibility = Visibility.PRIVATE)
                     ^
  symbol:   method productionVisibility()
  location: @interface VisibleForTesting
/home/ivar/tsunami-security-scanner-callback-server/storage/src/main/java/com/google/tsunami/callbackserver/storage/RedisInteractionStore.java:47: error: cannot find symbol
  @VisibleForTesting(productionVisibility = Visibility.PRIVATE)
                                            ^
  symbol:   variable Visibility
  location: class RedisInteractionStore
3 errors

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':tcs-storage:compileJava'.
> Compilation failed; see the compiler error output for details.

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Get more help at https://help.gradle.org

Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.
See https://docs.gradle.org/6.5/userguide/command_line_interface.html#sec:command_line_warnings

BUILD FAILED in 5s
9 actionable tasks: 6 executed, 3 up-to-date