check: add `--format` flag, json reporter #663

adrienthebo · 2025-10-19T02:17:16Z

Pull Request Checklist

The Rayhunter team has recently expressed interest in reviewing a PR for this. If not, this PR may be closed due our limited resources and need to prioritize how we spend them.
Added or updated any documentation as needed to support the changes in this PR.
Code has been linted and run through cargo fmt
If any new functionality has been added, unit tests were also added
- No tests are present in ./check but I can add them if needed
./CONTRIBUTING.md has been read

Problem

Rayhunter check output is emitted as plain text and doesn't lend itself to easy analysis by other tools.

Solution

Implement a --report flag, preserve the existing behavior as the default (manually invoked with --report log), and add an ndjson formatter.

Fixes #570.

Verification

Example output

❯ cargo run -- --path ../../rayhunter-traces/1749319445-goodsim.ndjson --report ndjson
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.07s
     Running `/Users/adrienthebo/personal/projects/radio/rayhunter-work/rayhunter/target/debug/rayhunter-check --path ../../rayhunter-traces/1749319445-goodsim.ndjson --report ndjson`
INFO  [rayhunter_check] Analyzers:
INFO  [rayhunter_check]     - Identity (IMSI or IMEI) requested in suspicious manner (v3): Tests whether the ME sends an Identity Request NAS message without either an associated attach request or auth accept message
INFO  [rayhunter_check]     - Connection Release/Redirected Carrier 2G Downgrade (v1): Tests if a cell releases our connection and redirects us to a 2G cell.
INFO  [rayhunter_check]     - LTE SIB 6/7 Downgrade (v1): Tests for LTE cells broadcasting a SIB type 6 and 7 which include 2G/3G frequencies with higher priorities.
INFO  [rayhunter_check]     - Null Cipher (v1): Tests whether the cell suggests using a null cipher (EEA0)
INFO  [rayhunter_check]     - NAS Null Cipher Requested (v1): Tests whether the MME requests to use a null cipher in the NAS security mode command
INFO  [rayhunter_check]     - Incomplete SIB (v2): Tests whether a SIB1 message contains a full chain of followup sibs

1749319445-goodsim.ndjson

{"analyzers":[{"name":"Identity (IMSI or IMEI) requested in suspicious manner","description":"Tests whether the ME sends an Identity Request NAS message without either an associated attach request or auth accept message","version":3},{"name":"Connection Release/Redirected Carrier 2G Downgrade","description":"Tests if a cell releases our connection and redirects us to a 2G cell.","version":1},{"name":"LTE SIB 6/7 Downgrade","description":"Tests for LTE cells broadcasting a SIB type 6 and 7 which include 2G/3G frequencies with higher priorities.","version":1},{"name":"Null Cipher","description":"Tests whether the cell suggests using a null cipher (EEA0)","version":1},{"name":"NAS Null Cipher Requested","description":"Tests whether the MME requests to use a null cipher in the NAS security mode command","version":1},{"name":"Incomplete SIB","description":"Tests whether a SIB1 message contains a full chain of followup sibs","version":2}],"rayhunter":{"rayhunter_version":"0.7.1","system_os":"Darwin 24.6.0","arch":"arm64"},"report_version":2}
{"packet_timestamp":"2025-06-07T21:03:24.743Z","events":[{"event_type":"Informational","message":"Identity Request happened but its not suspicious yet. (packet 12761)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-07T21:35:41.969Z","events":[{"event_type":"Informational","message":"Identity Request happened but its not suspicious yet. (packet 15242)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-07T22:10:20.991Z","events":[{"event_type":"Informational","message":"Identity Request happened but its not suspicious yet. (packet 18097)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-07T22:10:23.290Z","events":[{"event_type":"Informational","message":"Identity Request happened but its not suspicious yet. (packet 18138)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-08T03:30:56.706Z","events":[{"event_type":"Informational","message":"SIB1 scheduling info list was malformed (packet 30097)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-08T03:30:57.067Z","events":[{"event_type":"Informational","message":"SIB1 scheduling info list was malformed (packet 30098)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-08T03:30:59.228Z","events":[{"event_type":"Informational","message":"SIB1 scheduling info list was malformed (packet 30102)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-08T08:46:57.462Z","events":[{"event_type":"High","message":"Identity requested after auth request (packet 30765)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-08T08:46:58.205Z","events":[{"event_type":"High","message":"Disconnected after Identity Request without Auth Accept (packet 30769)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-08T09:22:13.650Z","events":[{"event_type":"High","message":"Identity requested after auth request (packet 32055)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-08T09:22:14.535Z","events":[{"event_type":"High","message":"Disconnected after Identity Request without Auth Accept (packet 32059)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-08T12:20:30.716Z","events":[{"event_type":"High","message":"Identity requested after auth request (packet 35219)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-08T12:20:31.447Z","events":[{"event_type":"High","message":"Disconnected after Identity Request without Auth Accept (packet 35224)"}],"skipped_message_reason":null}
{"packet_timestamp":"2025-06-08T21:22:34.877Z","events":[{"event_type":"High","message":"Identity requested after auth request (packet 121675)"}],"skipped_message_reason":null}

Considerations

~~The use of a dyn Trait feels a bit clumsy~~
Reconcile status logging
- log macros now write to stderr
- --report now writes a file so there's no issue of redirection writing extra logs.
Deal with multiple files
- as check: add flag help documentation #662 indicates the --path flag can be either a file or directory so this may need to emit multiple json reports in one shot
- We write one report per file

adrienthebo · 2025-10-20T04:00:34Z

check/src/main.rs

+            return;
+        }
+
+        let events = row


Note that this will compress out None values; the daemon/src/analysis.rs AnalysisWriter will not perform that compression. We could push this log into that writer as well if desired.

check/src/main.rs

adrienthebo · 2025-10-22T20:39:27Z

I'm pretty slammed with work right now, will follow up on this within the next week.

untitaker · 2025-10-22T20:41:12Z

so far it looks good to me. I am not worried about the use of dyn, ok to keep as is. I would recommend moving all logging to stderr though (unconditionally)

adrienthebo · 2025-10-27T04:58:43Z

This is ready for review; I haven't written rust in a few years and I'm unattached to this implementation so I'm happy to steer this change wherever needed.

untitaker

first wave of review, i think the direction is good but if the format is supposed to match then we should be able to share code.

check/src/main.rs

untitaker · 2025-10-27T17:02:02Z

check/src/main.rs

+    writer: BufWriter<File>,
+}
+
+// The `njson` report has the same output format as the daemon analysis report.


can it be made so that the structs are then actually shared between check and daemon? okay to move things into lib/

particularly, the definition of OutputRow and all code that converts to that structure

Extracted a DetectionRow in ea6e73e. At present the daemon doesn't perform the same row collapsing so I'll add that logic in a separate PR to separate that behavior change.

I'll need to take another pass at this since the first pass of using TryFrom doesn't seem ideal.

untitaker · 2025-10-27T17:04:42Z

check/Cargo.toml

+
+[dependencies.simple_logger]
+version = "5.0.0"
+features = ["stderr"]


can you document here why it has to be stderr?

It's no longer strictly necessary to log to stderr; my original implementation printed json to stdout for simplicity but since --path supports both files and directories we have to write .ndjson files in order to have a coherent output that matches the daemon ndjson output.

My instinct is to revert this change and continue logging to stdout so that check ... | less will work as expected, but I don't have strong feelings either way. I'll document why we made this change if you want to continue with the switch to stderr.

i think logging to stderr is still the right thing to do, just asking about documentation

Amended in b877ce4.

adrienthebo · 2025-10-29T04:13:08Z

lib/src/analysis/analyzer.rs

+    fn try_from(ar: AnalysisRow) -> Result<DetectionRow, Self::Error> {
+        let events: Vec<Event> = ar.events.into_iter().filter_map(|e| e).collect();
+
+        if events.is_empty() {


This will break skip reason generation. TryFrom might be a poor fit here because we need to be able to return an output row with n events or a skip reason and TryFrom doesn't make this configurable without passing a tuple, and at that point it's starting to abuse the TryFrom semantics.

adrienthebo · 2025-10-29T04:13:49Z

check/src/main.rs

+            }
+        }
+
+        let det = DetectionRow::try_from(row).ok();


Needs to handle skip reasons.

adrienthebo · 2025-10-29T04:14:42Z

check/src/main.rs

+
+// The `njson` report has the same output format as the daemon analysis report.
+// See also: [Newline Delimited JSON](https://docs.mulesoft.com/dataweave/latest/dataweave-formats-ndjson)
+impl NdjsonReport {


This could likely reuse the daemon AnalysisWriter struct. Since we're going to be refactoring to reuse components then extracting and reusing that struct will be worth the lift.

adrienthebo force-pushed the alt/check/json-reporter branch 2 times, most recently from c2cb8cc to 524059d Compare October 20, 2025 03:59

adrienthebo commented Oct 20, 2025

View reviewed changes

adrienthebo force-pushed the alt/check/json-reporter branch from 524059d to b46ae62 Compare October 20, 2025 04:03

adrienthebo commented Oct 20, 2025

View reviewed changes

check/src/main.rs Outdated Show resolved Hide resolved

adrienthebo commented Oct 20, 2025

View reviewed changes

check/src/main.rs Outdated Show resolved Hide resolved

adrienthebo commented Oct 20, 2025

View reviewed changes

check/src/main.rs Outdated Show resolved Hide resolved

adrienthebo added 6 commits October 26, 2025 21:12

check: add --report flag for writing ndjson output

cea78b3

check: format

add40da

check: clean up summarization

1328f45

check: use consistent naming

999826f

check: relocate report construction

73c552e

check: move logging to stderr

b881cc5

adrienthebo force-pushed the alt/check/json-reporter branch from 7f8bdb1 to b881cc5 Compare October 27, 2025 04:12

check: fix lints

b3a2aa7

adrienthebo marked this pull request as ready for review October 27, 2025 04:26

untitaker reviewed Oct 27, 2025

View reviewed changes

adrienthebo added 3 commits October 28, 2025 20:41

lib: extract DetectionRow out of check

ea6e73e

analyzer: simplify AnalysisRow destructuring

14d7bee

check: drop unused imports

cdd6d9e

adrienthebo commented Oct 29, 2025

View reviewed changes

check/src/main.rs

}

}

let det = DetectionRow::try_from(row).ok();

Copy link

Contributor Author

adrienthebo Oct 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs to handle skip reasons.

adrienthebo commented Oct 29, 2025

View reviewed changes

untitaker marked this pull request as draft November 2, 2025 23:50

check: document log destination reasoning

b877ce4

check: add --format flag, json reporter #663

Are you sure you want to change the base?

check: add --format flag, json reporter #663

Conversation

adrienthebo commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Checklist

Problem

Solution

Verification

Considerations

Uh oh!

adrienthebo Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adrienthebo commented Oct 22, 2025

Uh oh!

untitaker commented Oct 22, 2025

Uh oh!

adrienthebo commented Oct 27, 2025

Uh oh!

untitaker left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adrienthebo Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

check: add `--format` flag, json reporter #663

check: add `--format` flag, json reporter #663

adrienthebo commented Oct 19, 2025 •

edited

Loading

adrienthebo Oct 20, 2025 •

edited

Loading

adrienthebo Oct 29, 2025 •

edited

Loading