Parsing library for Tor-specific data formats.
Go Shell
Latest commit b9f5b78 Jul 17, 2016 David Fifield Refactor descriptor parsing to work over io.Readers.
The most basic parsing functions now take io.Reader rather than
*os.File. The existing functions such as ParseDescriptorFile have been
rewritten to be in terms of the more basic functions. The lowest-level
functions also decouple type annotation handling from parsing the rest
of the descriptor.

For example, the function ParseDescriptorFile now calls
parseDescriptorFile, which just opens the named file and passes the
resulting io.Reader to parseDescriptor. parseDescriptor reads and checks
the type annotation, then calles parseDescriptorUnchecked ("unchecked"
because it assumes the type annotation has already been checked and

ParseUnknownFile is now in terms of a lower-level parseWithAnnotation
that looks at a pre-read Annotation and dispatches to either
parseDescriptorUnchecked or parseConsensusUnchecked.

This change leaves GetAnnotation and CheckAnnotation unused by the other
parts of the API. It adds one new exported function: ParseUnknown
(non-file counterpart to ParseUnknownFile).
Failed to load latest commit information.
scripts Add function to get descriptor from digest. Jul 16, 2015
.gitignore Initial commit Dec 1, 2014
.travis.yml Add Travis CI file. Aug 15, 2015
LICENSE Update copyright. Apr 5, 2015 Elaborate and add links. Jun 12, 2016
consensus.go Refactor descriptor parsing to work over io.Readers. Jul 17, 2016
consensus_test.go Refactor descriptor parsing to work over io.Readers. Jul 17, 2016
descriptor_test.go Have DissectFile and extract* use the bufio.SplitFunc interface. Jul 17, 2016
generic.go Refactor descriptor parsing to work over io.Readers. Jul 17, 2016
generic_test.go Use the testing Skip functions to skip tests and benchmarks. Jul 17, 2016
util_test.go Make readAnnotation and readAndCheckAnnotation functions. Jul 17, 2016

zoossh logo

Build Status


Zoossh is a Go parsing library for Tor-specific data formats. It can parse consensuses and server descriptors. I originally wrote zoossh as a speedy fundament for sybilhunter, a tool to find Sybils in the Tor network. I have no need for other file types, so if zoossh doesn't provide what you need, check out the libraries below.

Supported file formats

Zoossh partially supports the following two file formats:

  • Server descriptors (@type server-descriptor 1.0)
  • Network status consensuses (@type network-status-consensus-3 1.0)

For more information about file formats, have a look at CollecTor.


Here's how you can parse a network status document and iterate over all relay statuses:

consensus, err := zoossh.ParseConsensusFile(fileName)
if err != nil {
    // Handle error.

for status := range consensus.Iterate(nil) {

Similarly, here's how you can parse a file containing server descriptors:

descriptors, err := zoossh.ParseDescriptorFile(fileName)
if err != nil {
    // Handle error.

for desc := range descriptors.Iterate(nil) {

For more details, have a look at zoossh's GoDoc page.


Check out the Python library Stem or the Java library metrics-lib. Both have more comprehensive support for data formats. There is also a comparison available online between Stem, metrics-lib, and zoossh.


Contact: Philipp Winter
OpenPGP fingerprint: B369 E7A2 18FE CEAD EB96 8C73 CF70 89E3 D7FD C0D0