# TrafficEye: finding web attacks in captured traffic

> TrafficEye is a blue-team tool for analysing captured packet files, matching configurable regular expression rules against specific parts of HTTP traffic, extracting binaries from sessions, and replaying requests. The repository publishes documentation and prebuilt builds rather than source, and it carries no stated licence.

**CuriousLearnerDev/TrafficEye** —  This tool is designed to help penetration testers and network administrators identify potential security threats, especially those targeting web applications such as SQL injection, XSS, and WebShells. Its modular desig 该工具适用于 HW 蓝队对网络流量的深入分析，帮助安全研究人员、渗透测试人员及网络管理员等专业人士识别潜在的安全威胁，尤其是针对 Web 应用的攻击（如 SQL 注入、XSS、WebShell 等）。其模块化设计使用户能够根据实际需求自由选择并定制各类功能模块

- Repository: https://github.com/CuriousLearnerDev/TrafficEye
- Stars: 657 · Forks: 78
- Language: Unknown
- License: not declared
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/curiouslearnerdev-trafficeye

## A tool for the blue side of a traffic capture

The overview section is where the positioning becomes clear. TrafficEye is designed for blue-team defence and network traffic analysis, and it helps identify security threats in captured traffic, especially web attacks such as SQL injection, XSS and WebShells. The Chinese description names the same audience from the other direction, saying the tool suits blue-team analysis of network traffic in HW-style defence exercises and that security researchers, penetration testers and network administrators are the intended users. The scope is therefore a capture file and the questions you want to ask of it. Was there an attempt at directory traversal in this export, does this request look like an injection attempt, and what file did that upload actually contain. The modular design is the other half of the pitch, since it lets you enable and customise the feature modules according to what the incident needs. The audience for a tool like this is a responder who already has a pcap and a question, not a builder of a detection platform, and the documentation, in both English and Chinese, is written for that person. The features list is long, covering extraction of binaries, statistics, log analysis, replay and AI assisted detection, and the sections below pick the parts that explain how the thing actually works.

## You install a release, because the repository is documentation

The top level of the repository is worth looking at before anything else, because it contains only a .gitignore, README.md and README_CN.md. The code is not published there. What is published are prebuilt downloads through the GitHub releases page, and the README documents how to run one. Python 3.10 or newer is required, and the sequence is a virtual environment, the requirements, and then the entry point.

```bash
cd TrafficEye
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python mian.py
```

Two details deserve attention. The activation command differs per platform, which is normal, and the last line is spelled mian in the README, so the filename in the documentation is probably a typo that you will have to reconcile with the archive you downloaded. There is also a platform-specific step that is easy to miss, because it appears as a single line after the block: on Linux you also need to make a helper executable by running chmod +x lib/log_identification. That helper is the log identification component, and the log analysis feature list names the formats it targets, namely Apache, Nginx, JSON, F5, HAProxy, Tomcat and IIS. The release naming is unusual, with tags like 0.0.11.0 and 0.0.8.92 and release titles that include a development label, which tells you the versioning is not a scheme you should write tooling against.

## The rule engine and its location identifiers

Detection is driven by rules in config.yaml, under the safety_testing section, and the interesting design decision is that each rule states where to look rather than only what to match. The identifiers are the vocabulary for that, and they are worth reading as a list because it is effectively the query language of the tool. ALL matches every field globally, and a leading exclamation mark excludes a field, so you can write a rule that applies everywhere except one place. URI is the full URL, URI_key and URI_value split the query string into parameter names and values. ALL_headers covers every request header, while headers:xxx selects a single one such as headers:cookie. The body side is split by content type: forms_body, forms_key_body and forms_value_body for form encoded data, json_body with json_key_body, json_value_body and json_item_body for JSON, xml_body with xml_value_body and xml_attribute_body for XML, and multipart_body with multipart_file_name_body, multipart_content_type_body and multipart_data_body for uploads. There is also binary for raw binary content. The rule structure itself is small, with a risk identifier, a display name, the detection locations, one or more regular expressions, and a severity of High, Medium or Low.

```yaml
risk_id:
  name:
    - Rule display name
  detection_location:
    - Target fields (multiple allowed, separated by `|`)
  rules:
    - Regular expression (one or more)
  severity:
    - Severity level (High / Medium / Low)
```

## A directory traversal rule, and what each field means

The example rule in the README is a directory traversal check, and it shows the whole idiom in one entry. The display name says it is a directory traversal payload using the parent directory forms, the detection location names five fields to inspect while excluding the referer header, the expression matches two or three dot path segments preceded or followed by a separator, and the severity is Medium.

```yaml
safety_testing:
  Directory_Traversal_Attack:
    name:
      - "Directory traversal payload using (/../) or (/.../)"
    detection_location:
      - 'URI|forms_key_body|multipart_file_name_body|ALL_headers|xml_value_body|!headers:referer'
    rules:
      - >-
        (?:(?:^|[\x5c/;])\.{2,3}[\x5c/;]|[\x5c/;]\.{2,3}[\x5c/;])
    severity:
      - Medium
```

The five fields and the exclusion are worth reading separately, because they explain the false positive behaviour. The URI field catches a full URL such as a download endpoint with a parent directory sequence in the query string. forms_key_body catches the same trick in a form field name. multipart_file_name_body catches it in an uploaded filename, which is the classic route to a web shell. ALL_headers catches it anywhere in the headers, and xml_value_body catches it inside an XML node value. The exclusion of headers:referer is the one rule-level judgement in the example, and it exists because a referer header legitimately contains parent directory sequences when a page links to a relative path, so matching there produces noise. That pattern, a broad location set with one targeted exclusion, is the template you would follow when writing your own rules, and it is why the identifier list is documented in such detail.

## tshark instead of pyshark, and decrypted HTTPS

Two implementation choices affect how you run this on a real capture. The first is the packet parsing layer. The features list names pyshark, but also describes an optimised tshark integration that the README claims is roughly one hundred times faster than pyshark, moving the analysis from minutes to seconds. That claim is the project's own, and it is plausible because tshark is a native parser while pyshark drives it through a Python layer, but it is stated rather than demonstrated here, so treat it as a design claim to test on your own captures. The second is HTTPS. The tool can decrypt HTTPS traffic using an sslkeys.log, which is the standard TLS key log format used by tools such as Wireshark, and that capability is what makes the detection rules useful against encrypted web traffic rather than only plaintext HTTP. The input formats are the full packet files,.pcapng,.pcap and.cap, plus DNS, and the tool performs automatic file type detection before analysis, so you are not required to tell it what it is looking at. For an incident workflow, the practical sequence is that you already have the capture and the keys, you point the tool at the file, and the rules run over the reconstructed HTTP traffic.

## Extraction, statistics and the replay features

The bulk of the feature list is about getting data out of a capture. There is export of HTTP data for Burp Suite, export of a POST body as a byte stream and as raw hex, and filtering by URI, request or response. There is binary extraction across a wide range of formats, which is the part that matters most in a web shell investigation: Java serialized data, C# serialized data and its base64 variant, Java bytecode, archives such as ZIP, 7z, RAR, TAR, GZ and ARJ, documents, email containers such as MBOX, PST, DBX and EML, databases including SQLite, MySQL and MongoDB, media, and detection of binary signatures. There are statistics too, with URI access counts, hit counts, HTTP methods, raw IP and IP geolocation. The replay features need a careful paragraph of their own, because they are where a defensive tool crosses into active behaviour. The tool can replay a request as-is or send the full binary request data, and it has a session replay mode where requests are sent in the original session order, with the documented example being a web shell tool that issues three requests as one test session, where you enter the session identifier to replay all three and reproduce the session. That capability is invaluable for confirming what an attacker actually did, and it is also the part you must only use in an environment you are authorised to test, because it sends crafted payloads to a live target. The AI detection section, covering targeted URI analysis, automated batch analysis and header or body analysis, is the least documented part of the tool and the one with the least detail about how the results are produced.

## The boundary of the tool, and the questions to ask first

Three limits are worth stating before you rely on this in an investigation. The first is the licence and the source. The repository lists no licence and no primary language, and it contains only documentation, so the analysis you run is a binary from a release page that you cannot audit, and you have no basis on which to redistribute it or embed it in a workflow. The second is the rule coverage. The security detection list covers information disclosure, sensitive file leaks, directory traversal, remote and local file inclusion, remote code execution, SQL injection and cross-site scripting, and each of those is a regular expression over selected fields, which means both false negatives on obfuscated payloads and false positives on benign input, and a clean report is evidence of no match, not evidence of no attack. The third is the operational boundary that the replay features create. A tool that can resend captured requests, including web shell sessions, belongs in a lab or in a system you own or have written permission to test, and mixing that into a production network where the capture came from real user traffic is a decision that needs a policy behind it, not just a checkbox. The maintenance picture is not the concern here: the last push was on 2026-08-04 and the newest release, 0.0.11.0, was published on 2026-08-03, so the project is being worked on, and the release titles carry a development label that suggests you should expect the behaviour to shift between builds.

## Conclusion

Adopt TrafficEye if you are on the defensive side of an incident, you have traffic captures, and you want a rule set you can edit yourself rather than a closed detection product. It does not fit a team that needs to audit the source, because the repository holds only the readme files and a gitignore while the code arrives as prebuilt downloads, and it does not fit an environment where unlicensed software is a problem, since no licence is stated. Before you run it against anything live, confirm you have authorisation for the systems involved, since the replay features send captured requests back out, and read the detection identifiers in config.yaml before trusting a clean result.

## FAQ

### What is TrafficEye and who is it for?

It is a tool for blue-team defence and network traffic analysis that identifies security threats in captured traffic, especially web attacks such as SQL injection, XSS and WebShells. The README names security researchers, penetration testers and network administrators as the intended users.

### How do I install and run TrafficEye?

The code is not in the repository, which holds only the readme files and a gitignore, so you download a prebuilt build from the GitHub releases page. It requires Python 3.10 or newer, and the README walks through creating a virtual environment, installing the requirements, and running the entry point, with an extra chmod step on Linux for the log identification helper.

### How do the detection rules in config.yaml work?

Rules live under the safety_testing section and each one has a display name, one or more detection locations, one or more regular expressions and a severity of High, Medium or Low. The detection locations are identifiers such as URI, ALL_headers, forms_key_body, json_value_body and multipart_file_name_body, and an identifier prefixed with an exclamation mark excludes that field.

### What is the difference between the pyshark and tshark approaches in TrafficEye?

The features list names pyshark and also an optimised tshark integration which the README describes as roughly one hundred times faster, turning analysis from minutes into seconds. That figure is the project's own claim, and the tool also performs automatic file type detection before analysis and supports HTTPS decryption with an sslkeys.log file.

### Can TrafficEye replay captured requests?

Yes. It can replay a request as-is or send the full binary request data, and its session replay mode sends requests in the original session order, so a multi request web shell session can be reproduced by entering the session identifier. Because that sends payloads to a live target, it should only be used on systems you are authorised to test.

## Sources

- [CuriousLearnerDev/TrafficEye on GitHub](https://github.com/CuriousLearnerDev/TrafficEye)
- [Issues](https://github.com/CuriousLearnerDev/TrafficEye/issues)
- [README](https://github.com/CuriousLearnerDev/TrafficEye/blob/master/README.md)
- [Releases](https://github.com/CuriousLearnerDev/TrafficEye/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/curiouslearnerdev-trafficeye