abstracta / wiresham

Simple TCP service mocking tool for replaying https://www.wireshark.org and http://www.tcpdump.org captured service traffic

Simple TCP mocking tool for replaying tcpdump or Wireshark captured service or client traffic.

If you like this project, please give it a star ⭐! This helps the project be more visible, gain relevance and encourages us to invest more effort in new features.

Description

This project is inspired in other tools like WireMock, mountebank and MockTCPServer, but provides following features that are partially supported by listed tools:

• TCP mocking support, with async messages sent (i.e: allows sending welcome messages which are not supported by mountebank).
• Load mocking specification from tcpdump .pcap or Wireshark .json dump files and provides a reduced .yaml format for easy versioning.
• Allows to easily run the mock embedded in Java projects for easy testing
• Allows both mocking servers and clients.

Take into consideration that this tool is very simple, and only replays TCP traffic that has previously been recorded, so if user (or server) interacts with the tool in unexpected ways, then the mock will not answer until next expected packet is received. For more complex scenarios consider using one of previously mentioned tools.

Usage

This tool (as previously listed ones) is particularly useful to implement integration tests without the hassle of flaky connections, or complex environment setup or restrictions (VPN, quotas, etc).

Note: If you use .pcap, since Wiresham uses pcap4j for .pcap files support, you need to install libpcap or winpcap as detailed in pcap4j website.

The general use case for the tool takes following steps:

1. User captures traffic with tcpdump (with something like tcpdump port 23 -w ~/traffic.pcap) or Wireshark between a client application and a service.

2. If traffic has been captured with Wireshark then store the captured traffic, filtering with proper condition for service port, in a .json file (File -> Export Packet Dissections -> As JSON...)

3. At this point user might follow three potential courses:

   1. Start Wiresham in standalone mode with stored .pcap or .json and connect to it with the client application to reproduce previously stored traffic.

      E.g.: java -jar wiresham-standalone.jar -p 2324 -a 0.0.0.0 wireshark-dump.json

      Latest version of wiresham-standalone.jar can be downloaded from maven central.

      A similar example for a tcpdump traffic:

      E.g.: java -jar wiresham-standalone.jar -p 2324 -a 0.0.0.0 traffic.pcap

      Run java -jar wiresham-standalone.jar -h to get usage instructions and help.

   2. Same as previous one but start Wiresham in standalong mode to emulate a client application (instead of a service application):

   E.g.: java -jar wiresham-standalone.jar -t 0.0.0.0:23 -a 0.0.0.0 wireshark-dump.json

   Note that the only difference with previous example is the use of -t to specify target server address instead of the -p option to specify the local port.

   1. Convert the tcpdump or Wireshark dump to a reduced .yaml file (an example file can be found in simple.yaml), optionally manually tune it (response times or binary packets), add it to the project repository and implement tests using VirtualTcpService class or VirtualTcpClient class.

      To convert a script run something like java -jar wiresham-standalone.jar -d reduced-dump.yml -a 0.0.0.0 wireshark-dump.json.

      To add Wiresham as dependency in maven project include in pom.xml the dependency:

      <dependency>
       <groupId>us.abstracta</groupId>
       <artifactId>wiresham</artifactId>
       <version>0.1</version>
      </dependency>

      Check what is the latest version in releases

      Check VirtualTcpServiceTest and VirtualTcpClientTest for simple and raw examples on how to use the classes.

Must-know features

Multiple port

There are some scenarios where we need to mock several services under the same domain but differing from port. For such scenarios multiple port support was added. Here there is a flow example on how a YAML would look:

- !server {data: FFFF, delayMillis: 10, port: 2324}
- !client {data: FFFF}
- !server {data: FFFF, port: 2325}
- !client {data: FFFF}
- !server {data: FFFF}

Important considerations:

1. Connections can be established at any time
2. Dump is read sequentially. Meaning that any packet received out of order will be ignored (parallelism not yet supported)
3. When a port is defined, subsequent packets until another port is defined will use the mentioned port without having to explicitly define it (as shown in the example)
4. Wireshark dumps and tcpdumps are parsed using multiple port when providing endpoint address using -a flag

   Note: if port is provided alonside with the address E.g: 0.0.0.0:23 only the specified port will be parsed otherwise, all involved ports will be part of the flow.

5. Client mode also supported

Tips

How to filter by port while using packet dissections

Since packet dissections are in JSON schema we can take advantage of using jq.

The filter to use can be applied using:

• Using jq playground (online version of jq). Here there is an example.
• Using jq cli. jq '<filter-here>' dissection-packets.json

Filter: . |= map(select((.["_source"].layers.tcp["tcp.srcport"] == "PORT_NUMBER") or (.["_source"].layers.tcp["tcp.dstport"] == "PORT_NUMBER")))

PORT_NUMBER needs to be replaced by the port we want to filter.

In short, this filter is going to exclude all packets that don't interact with the PORT_NUMBER we want.

Build

In case you want to build this project from scratch, it is required JDK8+ and maven 3.3+.

Then just run mvn clean install and the library (and standalone version) will be built and installed in the local maven repository.

Release

To release the project, define the version to be released by checking included changes since last release and following semantic versioning. Then, create a release (including v as prefix of the version, e.g. v0.1), this will trigger a GitHub Actions workflow which will publish the jars to maven central repository (and make it general available to be used as maven dependency projects) in around 10 mins and can be found in maven central search after up to 2 hours.

wiresham's Issues

Documentation on how to use wiresham with practical examples.

Hello. I'm wondering how to use WireSham to do TCP Mocking. Reading the documentation in GitHub, I realized that the tool does not have a graphical interface, but a framework written in java that should be low and executed, for example, using the Eclipse IDE. Is that right?
If so, do you have any documentation that you can provide with the step-by-step guide on how to use WireSham?
If yes, please send them to my email: [email protected].

Dynamic content in flow definition

Hi,
I found your tool useful, but what is missing from my point of view is lack of possiblity to define dynamic content for req/resp.

E.g.
in our case per every connection established content and sequence should be the same with exception of value for id of content e.g. value of articleId field, value of contentId field etc

What I want to achieve is to test scenario with two connections running in parallel and talking in the same steps but with different values inside data.

Would it be possibe to add such feature?
Or maybe you could advice how such funcionality may be added?

Thanks,
Lukasz

Wiresham 0.6 artifact to maven central

Wiresham 0.6 is not available in the maven central

A way to verify if VirtualTcpService was called

Hi, thanks for a great library! I'm looking for a functionality, that will tell me if my VirtualTcpService instance has received any request. Preferably even a way to see what was called and how many times. Do you have an idea how to approach this task using WireSham?

A way to import wireshark json using port number

The server and client within the imported wireshark json file might have
the same IP address. In this case it would be useful to add port number
to method Flow.fromWiresharkJsonDump

support mocking of multiple server ports in a single instance

it would be great if data of multiple ports of a server could be simulated in a single instance. so that they are played back synchronously rather than independently in different program instances .

--read-buffer-size-bytes option seems not working

I exported json from Wireshark and try to get wiresharm running.
It always gives me the same error, doesn't matter what I put to -b or --read-buffer-size-bytes option.

c:\myfolder>java -jar wiresham-0.2.1-standalone.jar --read-buffer-size-bytes 4096 -p 2324 -w 0.0.0.0 wireshark_export.json
Exception in thread "main" java.lang.IllegalArgumentException: Read buffer size of 2048 bytes is not enough for receiving expected packet from client with

Using wiresham to mock http request/response

Is it possible to use wiresham with curl or other http client to mock http traffic?

I captured some http requests and responces.

Started wiresham. the -vv option gives me some glimpse under the hood.

When I am sending a curl request identical to the captured, I can see in the log following output but curl just keep waiting:

19:44:08.464 [pool-2-thread-1] INFO us.abstracta.wiresham.ClientConnection - starting new flow ...
19:44:08.464 [pool-2-thread-1] DEBUG us.abstracta.wiresham.ClientPacketStep - Waiting for 474554202F72...2F2A0D0A0D0A
19:44:08.464 [pool-2-thread-1] TRACE us.abstracta.wiresham.ClientConnection - reading from socket
19:44:08.465 [pool-2-thread-1] TRACE us.abstracta.wiresham.ClientConnection - read from socket: 474554202F72...2A2F2A0D0A0D0A
19:44:08.465 [pool-2-thread-1] TRACE us.abstracta.wiresham.ClientPacketStep - Searching for 474554202F72...3A202A2F2A0D0A0D0A from 0
19:44:08.465 [pool-2-thread-1] TRACE us.abstracta.wiresham.ClientPacketStep - Start match at 0
19:44:08.465 [pool-2-thread-1] DEBUG us.abstracta.wiresham.ClientPacketStep - received expected 474554202F7...02A2F2A0D0A0D0A
19:44:08.465 [pool-2-thread-1] DEBUG us.abstracta.wiresham.ClientPacketStep - Waiting for 485454502F312E3120...3656432336631227D7D7D0D0A300D0A0D0A
19:44:08.465 [pool-2-thread-1] TRACE us.abstracta.wiresham.ClientConnection - reading from socket
<both curl and wiresham waits indefinately>

Effectively, the mock server read and identified an expected request, but then instead of serving this request response it is waiting for it: 'Waiting for...' is the hex sequence for the http response.