fq README

The project's README from github.com/wader/fq. As one markdown file: README.md.

fq

Tool, language and decoders for working with binary formats.

fq demo

Basic usage is fq . file, fq d file or fq 'some query' file ....

For details see the manual, also available as man fq and as AsciiDoc.

Background

fq is a tool, language, and decoders for working with binary formats and data. In most cases it behaves and feels similar to jq and it also uses the same expression language. To get the most out of fq it's recommended to learn more about jq.

It features a structural hex viewer, nested format decoding, slicing and concatenating binary data, bit-level decoding and an interactive REPL with auto-completion.

Goals

Hopes

Supported formats

aac_frame, adts, adts_frame, aiff, amf0, apev2, apple_bookmark, ar, asn1_ber, av1_ccr, av1_frame, av1_obu, avc_annexb, avc_au, avc_dcr, avc_nalu, avc_pps, avc_sei, avc_sps, avi, avro_ocf, bencode, bitcoin_blkdat, bitcoin_block, bitcoin_script, bitcoin_transaction, bits, bplist, bsd_loopback_frame, bson, bytes, bzip2, caff, cbor, csv, dns, dns_tcp, elf, ether8023_frame, exif, fairplay_spc, fit, flac, flac_frame, flac_metadatablock, flac_metadatablocks, flac_picture, flac_streaminfo, gif, gzip, heif, hevc_annexb, hevc_au, hevc_dcr, hevc_nalu, hevc_pps, hevc_sps, hevc_vps, html, icc_profile, icmp, icmpv6, id3v1, id3v11, id3v2, ipv4_packet, ipv6_packet, jp2c, jpeg, json, jsonl, leveldb_descriptor, leveldb_log, leveldb_table, luajit, macho, macho_fat, markdown, matroska, midi, moc3, mosaic, mp3, mp3_frame, mp3_frame_vbri, mp3_frame_xing, mp4, mpeg_asc, mpeg_es, mpeg_pes, mpeg_pes_packet, mpeg_spu, mpeg_ts, msgpack, negentropy, nes, ogg, ogg_page, opentimestamps, opus_packet, pcap, pcapng, pg_btree, pg_control, pg_heap, png, prores_frame, protobuf, protobuf_widevine, pssh_playready, rtmp, safetensors, sll2_packet, sll_packet, stl, tap, tar, tcp_segment, tiff, tls, toml, tzif, tzx, udp_datagram, vorbis_comment, vorbis_packet, vp8_frame, vp9_cfm, vp9_frame, vpx_ccr, wasm, wav, webp, xml, yaml, zip

It can also work with some common text formats like URLs, hex, base64, PEM etc and for some serialization formats like XML, YAML, etc. it can transform both from and to jq values.

For details see the manual.

Presentations and media

Install

Use one of the methods listed below or download a pre-built release for macOS, Linux or Windows. Unarchive it and move the executable to PATH etc.

On macOS if you don't install using one of the method below then you might have to manually allow the binary to run. This can be done by trying to run the binary, ignore the warning and then go into security preference and allow it. Same can be done with these commands:

xattr -d com.apple.quarantine fq
# for macOS version before Sequoia you might need this also
spctl --add fq

Homebrew (macOS)

brew install wader/tap/fq

MacPorts

On macOS, fq can also be installed via MacPorts. More details here.

sudo port install fq

Windows

fq can be installed via scoop.

scoop install fq

Arch Linux

fq can be installed from the extra repository using pacman:

pacman -S fq

You can also build and install the development (VCS) package using an AUR helper:

paru -S fq-git

Gentoo

fq can be installed from the Gentoo package repository using emerge:

emerge dev-util/fq

Guix

guix shell fq -- fq --help # in develompen shell
guix install fq            # into current profile

Nix

nix-shell -p fq

FreeBSD

Use the fq port.

Alpine

Currently in edge testing but should work fine in stable also.

apk add -X http://dl-cdn.alpinelinux.org/alpine/edge/testing fq

Build from source

Make sure you have go 1.22 or later installed.

To install directly from git repository (no git clone needed):

# build and install latest release
go install github.com/wader/fq@latest

# build and install latest master
go install github.com/wader/fq@master

# copy binary to $PATH if needed
cp "$(go env GOPATH)/bin/fq" /usr/local/bin

To build, run and test from source:

# build and run
go run .
# build and run with arguments
go run . -d mp3 . file.mp3
# just build
go build -o fq .
# run all tests and build binary
make test fq

Development and adding a new decoder

See dev.md

This project would not have been possible without itchyny's jq implementation gojq. I also want to thank HexFiend for inspiration and ideas and stedolan for inventing the jq language.

Tools

Projects and Standards

TODO and ideas

See TODO.md

License

fq is distributed under the terms of the MIT License.

See the LICENSE file for license details.

Licenses of direct dependencies:

fq (wader/fq)

Searching Database…

10.6K ·GitHub
Fq
Что это такое?fq — это инструмент командной строки, язык и набор декодеров для работы с бинарными форматами; его часто описывают как jq для бинарных данных. Можно вывести структуру файла, выполнять запросы в стиле jq и изучать результаты в интерактивном REPL.
Так это программа с интерфейсом, библиотека для кода или то, что запускают в терминале?Это самостоятельный CLI-инструмент, написанный на Go, с интерактивным REPL и автодополнением. Вы устанавливаете один исполняемый файл и прямо из терминала выполняете запросы к файлам.
Как его установить и впервые посмотреть на файл?Установите через Homebrew на macOS, scoop на Windows, pacman или AUR на Arch, пакеты есть в Gentoo, Guix, Nix, FreeBSD и Alpine, либо скачайте готовый бинарник из релизов для macOS, Linux или Windows. Затем выполните fq . file, чтобы вывести структуру файла, или fq 'some query' file, чтобы отфильтровать.
Нужно ли знать jq, чтобы было от этого толк?Помогает: fq использует тот же язык выражений, что и jq, и в README советуют изучить jq, чтобы раскрыть инструмент полностью. Для сборки из исходников нужен Go 1.22 или новее; готовым бинарникам это не требуется.
Есть ли подводные камни при установке?На macOS вручную скачанный бинарник может быть заблокирован при первом запуске — нужно разрешить его в настройках безопасности (в README приведены точные команды). В остальном установка проходит без проблем на macOS, Linux и Windows.
Какие файлы он умеет декодировать?Список декодеров охватывает медиа (mp4, mp3, flac, jpeg, png, gif, webp, wav), исполняемые файлы (elf, macho), архивы (zip, tar), дампы сети и сетевые протоколы (pcap, pcapng, DNS, TLS, IPv4/IPv6), форматы сериализации (protobuf, bson, cbor, msgpack) и многое другое. Работает и с текстовыми данными вроде URL, hex, base64 и PEM, а также умеет преобразовывать XML и YAML в значения jq и обратно.
Что можно делать с открытым файлом?Он показывает структурированный hex-просмотрщик, декодирует вложенные форматы, поддерживает нарезку и склейку бинарных данных, декодирование на уровне битов и интерактивный REPL с автодополнением для изучения результатов.
Зачем автор его создал?Заявленные цели — сделать бинарные файлы доступнее, пригодными для запросов и нарезки, со вложенными форматами и побитовым декодированием в быстром и удобном CLI-инструменте. Проект построен на реализации gojq от itchyny и вдохновлён HexFiend и языком jq.
Чем он отличается от Wireshark, ImHex или HexFiend?В README они перечислены как родственные проекты с другим фокусом: HexFiend — hex-редактор для macOS с поддержкой шаблонов форматов, ImHex — hex-редактор для реверс-инженеров, Wireshark декодирует сетевой трафик, а kaitai выполняет декларативный разбор бинарных форматов. fq стремится объединить язык запросов в духе jq, REPL и широкий набор декодеров в одном CLI-инструменте.
What are similar projects?yq, brook, jq, scapy, grpcurl, liteparse, zenc, fx
Which topics is it in?packet-capture, repl, codec, xml, media, parsing, binary-analysis, parser, protocol, tls, reverse-engineering, json
Creator
wader
Size
53.2 MB
Stars
10.6K
Updated
CommitOct 16Releasev0.18.0Aug 25
Age
5y
Commits · 90 Days