Repository files navigation

Tool, language and decoders for working with binary data.

TLDR: it aims to be jq, hexdump, dd and gdb for files combined into one.

Basic usage isfq . file,fq d file orfq 'some query' file ....

For details seeusage.md.

fq is inspired by thejq tool and language and allows you to work with binary formats in the same way. In addition to using jq expressions it can also present decoded tree structures, transform, slice and concatenate binary data. It also supports nested formats and features an interactive REPL with auto-completion of functions and names.

It was originally designed to query, inspect and debug media codecs and containers like MP4, FLAC and JPEG but has since been extended to support a variety of formats like executables, packet captures (with TCP reassembly) and serialization formats like JSON, YAML, XML, CBOR, protobuf. In addition it also has functions to work with URLs, convert to/from hex, number bases, search for patterns etc.

• Make binaries more accessible, queryable and sliceable.
• Nested formats and bit-oriented decoding.
• Quick and comfortable CLI tool.
• Bits and bytes transformations.

• Make it useful enough that people want to help improve it.
• Inspire people to create similar tools.

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,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,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,sll2_packet,sll_packet,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 seeformats.md andusage.md.

• PBS Tidbit 8 of Y: Interview with jq Maintainer Mattias Wadman - English podcast episode about jq and some fq.
• Kodsnack 585 - Polymorfisk JSON - Swedish podcast episode about jq and fq
• "fq - jq for binary formats" atFOSDEM 2023 -video & slides
• "fq - jq for binary formats" atNo time to wait 6 -video -slides
• "fq - jq for binary formats" atBinary Tools Summit 2022 -video -slides

Use one of the methods listed below or download a pre-builtrelease for macOS, Linux or Windows. Unarchive it and move the executable toPATH 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 this command:

xattr -d com.apple.quarantine fq&& spctl --add fq

brew install wader/tap/fq

On macOS,fq can also be installed viaMacPorts. More detailshere.

sudo port install fq

fq can be installed viascoop.

scoop install fq

fq can be installed from theextra repository usingpacman:

pacman -S fq

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

paru -S fq-git

nix-shell -p fq

Use thefq port.

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

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

Make sure you havego 1.22 or later installed.

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

# build and install latest releasego install github.com/wader/fq@latest# build and install latest mastergo install github.com/wader/fq@master# copy binary to $PATH if neededcp"$(go env GOPATH)/bin/fq" /usr/local/bin

To build, run and test from source:

# build and rungo run.# build and run with argumentsgo run. -d mp3. file.mp3# just buildgo build -o fq.# run all tests and build binarymaketest fq

Seedev.md

This project would not have been possible withoutitchyny'sjq implementationgojq. I also want to thankHexFiend for inspiration and ideas andstedolanfor inventing thejq language.

• HexFiend - Hex editor for macOS with format template support.
• ImHex - A Hex Editor for Reverse Engineers.
• binspector - Binary format analysis tool with query language and REPL.
• kaitai - Declarative binary format parsing.
• Wireshark - Decodes network traffic (tip:tshark -T json).
• MediaInfo - Analyze media files (tipmediainfo --Output=JSON andmediainfo --Details=1).
• GNU poke - The extensible editor for structured binary data.
• ffmpeg/ffprobe - Powerful media libraries and tools.
• hexdump - Hex viewer tool.
• hex - Interactive hex viewer with format support via lua.
• hachoir - General python library for working binary data.
• scapy - Decode/Encode formats, focus on network protocols.

• Let's Solve the File Format Problem.
• PRONOM file format registry.
• Sustainability of Digital Formats at Library of Congress.
• Data Format Description Language (DFDL).

SeeTODO.md

fq is distributed under the terms of the MIT License.

See theLICENSE file for license details.

Licenses of direct dependencies:

• Forked version of gojq -https://github.com/itchyny/gojq/blob/main/LICENSE (MIT)
• github.com/ergochat/readline -https://github.com/ergochat/readline/blob/master/LICENSE (MIT)
• github.com/BurntSushi/toml -https://github.com/BurntSushi/toml/blob/master/COPYING (MIT)
• github.com/creasty/defaults -https://github.com/creasty/defaults/blob/master/LICENSE (MIT)
• github.com/gomarkdown/markdown -https://github.com/gomarkdown/markdown/blob/master/LICENSE.txt (BSD)
• github.com/gopacket/gopacket -https://github.com/gopacket/gopacket/blob/master/LICENSE (BSD)
• github.com/mitchellh/copystructure -https://github.com/mitchellh/copystructure/blob/master/LICENSE (MIT)
• github.com/mitchellh/mapstructure -https://github.com/mitchellh/mapstructure/blob/master/LICENSE (MIT)
• github.com/pmezard/go-difflib -https://github.com/pmezard/go-difflib/blob/master/LICENSE (BSD)
• golang/snappy -https://github.com/golang/snappy/blob/master/LICENSE (BSD)
• golang/x/* -https://github.com/golang/text/blob/master/LICENSE (BSD)
• gopkg.in/yaml.v3 -https://github.com/go-yaml/yaml/blob/v3/LICENSE (MIT)
• Parts of go crypto/tls and github.com/zmap/zcrypto -https://github.com/zmap/zcrypto/blob/master/LICENSE (Apache)