Traffic Analysis¶

friTap can do more than capture decrypted traffic — it can passively analyze it. A set of composable analyzers walk every reconstructed flow and emit structured findings: leaked credentials, indicators of compromise, decoded protobuf/gRPC, and more.

Overview¶

Traffic analysis is passive. Analyzers only read flows that friTap has already captured and decrypted — they never touch the target process, send packets, probe ports, or generate any network activity. The word "scan" here means scan the captured traffic, not scan the target.

There are two ways to run analyzers:

Both modes share the same analyzers, the same Finding/Severity model, the same reporters, and the same CI gate semantics.

Write your first analyzer¶

An analyzer is any object satisfying the BaseAnalyzer protocol: a name attribute plus an analyze_flow(self, flow) -> list[Finding] method. Here is a complete, working analyzer that flags any flow whose host ends in .internal — exactly the kind of leak you want a CI pipeline to catch.

Save this as my_analyzer.py:

from friTap.analysis import Finding, Severity


class InternalHostAnalyzer:
    """Flag requests to internal hostnames that should never leave the network."""

    # The user-facing name; also how you select it via --scanners.
    name = "internal-hosts"

    # Opt-in marker required for auto-discovery from a bare module reference.
    is_fritap_analyzer = True

    def analyze_flow(self, flow) -> list[Finding]:
        host = flow.display_host or ""
        if not host.endswith(".internal"):
            return []
        return [
            Finding(
                severity=Severity.MEDIUM,
                title="Request to internal host",
                description=f"Traffic observed to internal host {host}",
                source=self.name,
                flow_id=flow.flow_id,
                evidence={"type": "internal_host", "value": host},
            )
        ]

Load it with --analyzer-path and select it with --scanners:

fritap analyze capture.tap \
    --analyzer-path my_analyzer:InternalHostAnalyzer \
    --scanners internal-hosts \
    --report table

Ship it everywhere: discovery¶

Beyond the one-off --analyzer-path, an analyzer can be made ambiently available — picked up automatically by every fritap run, including --list-analyzers, the TUI, and offline analysis — through three discovery channels.

1. Drop-in analyzers directory¶

Drop a .py file containing a class with is_fritap_analyzer = True into the platform analyzers directory and it is auto-discovered everywhere:

No --analyzer-path needed — friTap scans this directory the first time analyzers are listed or run (discovery is lazy, then cached). This mirrors the existing plugins directory trust model.

2. Packaged analyzers (entry points)¶

Third-party packages distribute analyzers by declaring the fritap.analyzers entry-points group in their setup.py / pyproject.toml:

entry_points={
    "fritap.analyzers": [
        "my-analyzer = my_pkg.analyzers:MyAnalyzer",
    ],
}

Once the package is pip install-ed, the analyzer is discovered automatically.

3. Plugin bridge¶

A FriTapPlugin can expose analyzers by implementing the optional register_analyzers() hook, which returns a list of BaseAnalyzer instances. This runs independently of the on_load/Session lifecycle, so the analyzers are available offline, for --list-analyzers, and in the TUI:

from friTap.plugins.base import FriTapPlugin


class MyPlugin(FriTapPlugin):
    name = "my-plugin"
    version = "1.0.0"

    def register_analyzers(self):
        return [MyAnalyzer()]

Listing discovered analyzers¶

Both commands list every analyzer — built-in and discovered:

fritap --list-analyzers           # top-level flag
fritap analyze --list-analyzers   # under the analyze subcommand

export FRITAP_DISABLE_ANALYZER_DISCOVERY=1

Watch the CI gate trip¶

The MEDIUM severity above is deliberate. The default CI gate trips at medium or higher, so a single match makes the command exit non-zero:

fritap analyze capture.tap --analyzer-path my_analyzer:InternalHostAnalyzer
echo $?   # -> 2  (a medium+ finding was reported)

If you lower the analyzer's severity to Severity.LOW, the same run exits 0 — the finding is still reported, but it stays below the gate. See CI/CD gate for the full exit-code contract.

The analyze CLI¶

Run analyzers over a captured .tap file. Both forms are equivalent:

fritap analyze capture.tap          # bare subcommand
fritap --analyze capture.tap        # explicit flag

Flags¶

fritap analyze capture.tap --category pii --show-pii          # reveal redacted PII
fritap analyze capture.tap --source credentials --min-confidence 0.8

See api/cli.md for the canonical flag reference across all subcommands.

Live scan¶

Add --scan to any live capture to analyze flows as they complete, then print a report when capture ends. This is a functional, supported feature, not experimental.

fritap --scan -m com.example.app                  # all built-in analyzers
fritap --scan credentials,ioc -m com.example.app  # a subset

--scan takes an optional comma-separated analyzer list; with no value it runs all built-in analyzers (the argument is nargs="?" with a default of all).

Loading custom analyzers during a live capture now works the same as offline — --analyzer-path is repeatable, so you can stack several:

fritap --scan all -m com.example.app \
    --analyzer-path my_analyzer:InternalHostAnalyzer \
    --analyzer-path another_pkg.analyzers

The live --scan-* filters mirror the offline analyze filters one-for-one (--scan-min-confidence ≙ --min-confidence, --scan-source ≙ --source, --scan-category ≙ --category, --scan-show-pii ≙ --show-pii).

Analyzer catalog¶

friTap ships four built-in analyzers. Their names (used with --scanners/--scan) are credentials, ioc, privacy, and protobuf. All four run by default when you pass a bare --scan / --scanners (i.e. the full built-in set).

credentials¶

Scans HTTP headers, query parameters, request bodies, response bodies, and URLs for secrets. All reported secret values are redacted (first few characters only).

JWTs are detected anywhere in the body via pattern eyJ..., decoded without verification, and flagged CRITICAL if the header algorithm is none.

All reported secret values are redacted by default. The credentials analyzer tags every finding with metadata["category"] = "secret" (see Category taxonomy).

The API-key/secret pattern set:

ioc¶

Extracts Indicators of Compromise from connection metadata, HTTP headers, URLs, and response bodies. Most IOC findings are INFO — they are inventory, not alerts.

protobuf¶

Detects and decodes protobuf and gRPC content in HTTP flows.

Pass --protobuf-schema <path> to supply a schema. Non-gRPC bodies are decoded when the content-type indicates protobuf or the bytes heuristically look like protobuf.

privacy¶

Detects personally identifiable information (PII) leaking through observed traffic — headers, query parameters, JSON/form bodies, and URLs. Every finding is tagged metadata["category"] = "pii" and carries one or more compliance tags in metadata["compliance"] (e.g. GDPR, CCPA, PCI-DSS, HIPAA).

The privacy analyzer runs as part of the default built-in set.

Category taxonomy and compliance tags¶

Every finding now carries a category in metadata["category"], surfaced as the Finding.category property. The four categories are:

Filter the report by category with --category secret,pii (offline) or --scan-category (live). PII findings additionally carry metadata["compliance"], listing the regulatory regimes (GDPR, CCPA, PCI-DSS, HIPAA) implicated by that data type.

Finding and Severity model¶

Every analyzer emits Finding objects (friTap.analysis.Finding), an immutable dataclass:

The finding's category is exposed directly as the Finding.category property (reading metadata["category"]).

Severity (friTap.analysis.Severity) is declared most-severe first, so rank 0 is the most severe:

Finding.to_dict() is the single serialization contract shared by reporters, the .tap REC_FINDING record, and the findings sidecar (severity is stored as its string value). See api/tap-format.md for how findings are stored inside a .tap file.

Reports and the findings sidecar¶

Four report formats are available. The flag name depends on the mode: --report <fmt> selects the format for the offline fritap --analyze <file> path, while --scan-report <fmt> selects it for the live fritap --scan ... path. Both accept the same set of formats:

• table — aligned text table for the terminal (default), with a per-severity total line.
• json — {meta, summary, findings}; summary carries total, by_severity, and by_source counts.
• csv — columns severity,title,source,flow_id,confidence,description.
• md — Markdown report grouped by severity.

In addition, the analyze CLI always writes a JSON findings sidecar next to the input file: <tap_stem>.findings.json (e.g. capture.tap → capture.findings.json). This is independent of --report and is written even when --report-out redirects the main report elsewhere.

CI/CD gate¶

The analyze command is designed to be a CI gate. Its exit code:

Because --min-severity filters findings before the gate is evaluated, you can tune sensitivity: filtering to --min-severity critical lets a HIGH finding through the report list but, if nothing critical remains, the gate clears and the command exits 0.

# .github/workflows/traffic-analysis.yml
name: Traffic Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install friTap
      # Exit 2 (gate tripped by a medium+ finding) fails the job.
      - name: Analyze captured traffic
        run: fritap analyze capture.tap --report md --report-out analysis.md
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: traffic-analysis
          path: |
            analysis.md
            capture.findings.json

Programmatic API¶

The pure, presentation-agnostic entry point is analyze_tap_report(...), exported from the top-level friTap package. It performs no stdout, no sidecar write, and never calls sys.exit — it returns an AnalyzeReport you inspect yourself.

from friTap import analyze_tap_report

report = analyze_tap_report(
    "capture.tap",
    scanners="credentials,ioc",   # None / "all" / "" -> every built-in (which analyzers RUN)
    min_severity="info",
    report_format="table",
    include_private_ips=False,
    protobuf_schema=None,
    analyzer_path=None,           # "module" or "module:Class"
    min_confidence=0.0,           # report-side: drop findings below this confidence
    source=None,                  # report-side: comma-separated source names to SHOW
    category=None,                # report-side: "secret,pii,network,protocol" to SHOW
    show_pii=False,               # reveal PII/secret values instead of redacting
)

print(report.rendered)            # the formatted report string
print(report.analyzer_names)      # ['credentials', 'ioc']
for finding in report.findings:   # already severity-filtered
    print(finding.severity.value, finding.title)

# CLI-parity gate:
if report.gate_tripped:           # any finding >= report.gate_severity ("medium")
    raise SystemExit(report.exit_code)   # 2 when tripped, else 0

AnalyzeReport carries findings, rendered, report_format, analyzer_names, meta, and gate_severity, plus the gate_tripped and exit_code properties. analyze_tap_report raises ValueError for an unknown report_format or an unresolvable analyzer spec, and ImportError for a bad analyzer_path.

Lower-level building blocks¶

For finer control, compose the resolver and multi-analyzer runner directly:

from friTap.analysis import analyze_tap_multi
from friTap.analysis.registry import resolve_analyzers

analyzers = resolve_analyzers(
    "credentials,ioc",            # None / "all" / "" -> every built-in
    include_private_ips=False,
)
findings = analyze_tap_multi(analyzers, "capture.tap")

analyze_tap_multi reads the .tap once and passes each flow to every analyzer. There is also analyze_tap(analyzer, tap_path) for a single analyzer. The helper functions list_analyzers() and list_report_formats() enumerate the registered built-ins and formats. See api/python.md for the wider programmatic API.

Try it on the sample capture¶

The repository ships a sample .tap you can analyze immediately:

fritap analyze capture_20260507_153933.tap --report table
# or:  python -m friTap analyze capture_20260507_153933.tap --report table

This capture produces 860 findings (846 INFO, 13 LOW, 1 CRITICAL) across the ioc (847) and credentials (13) analyzers, and the command exits 2 — the single CRITICAL credential finding trips the medium gate.