Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pandatix/go-abnf
Augmented Backus-Naur Form (ABNF) in Go. Implements RFC 5234 and 7405, with Errata 2968 and 3076.
https://github.com/pandatix/go-abnf
abnf backtracking fuzzing golang grammar graph regex rfc5234 rfc7405
Last synced: 11 days ago
JSON representation
Augmented Backus-Naur Form (ABNF) in Go. Implements RFC 5234 and 7405, with Errata 2968 and 3076.
- Host: GitHub
- URL: https://github.com/pandatix/go-abnf
- Owner: pandatix
- License: mit
- Created: 2022-11-28T13:32:57.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-12T11:04:47.000Z (12 days ago)
- Last Synced: 2024-12-12T12:20:26.192Z (12 days ago)
- Topics: abnf, backtracking, fuzzing, golang, grammar, graph, regex, rfc5234, rfc7405
- Language: Go
- Homepage:
- Size: 396 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
Go-ABNF
Go module to handle Augmented Backus-Naur Form (ABNF), providing a large API.
It implements RFC 5234 and 7405, with Errata 2968 and 3076.
Capabilities:
- [X] parse ABNF (to manipulable datastructure ; with cycle detection)
- [X] compile ABNF to regex
- [ ] create a minimal set of tests that covers the full grammar
- [X] generate a visual representation of the ABNF grammar provided (mermaid)
- [X] create an ABNF fuzzer for your modules (version >= Go1.18beta1)
## How it works
Under the good, `go-abnf` is a dependency-free brute-force parser. It enumerates all possibilities for a given grammar and an input, and returns all possible paths. Those then have to be lexed in order to produce a new grammar.
As this implementation is not adhesive to the ABNF grammar of the ABNF grammar as defined in RFC 5234, updated by RFC 7405 and fixed by Erratum 2968 and 3076, it enables genericity.
This imply that for any valid grammar in ABNF that is properly lexed, if you can write a lexer for this grammar, you can parse new input with the original grammar. To init this loop, we had to hardcode the manual decomposition of the ABNF grammar, reviewed multiple times.
Examples can be found in [the examples directory](examples/)
## Fuzzing
As go-abnf revolves around grammars, you can use a random walk to traverse its graph and efficiently generate valid inputs according to a given grammar.
This is particularly powerfull when you want to fuzz Go implementations that require a very specific input format that the Go's fuzzing engine can't produce.
You can use go-abnf to efficiently produce test cases, as follows.
```go
package example
import (
_ "embed"
"testing"
goabnf "github.com/pandatix/go-abnf"
)
//go:embed my-grammar.abnf
var myGrammar []byte
func FuzzFunction(f *testing.F) {
g, err := goabnf.ParseABNF(myGrammar)
if err != nil {
f.Fatal(err)
}
f.Fuzz(func(t *testing.T, seed int64) {
// Generate a random test case based on the seed
b, _ := g.Generate(seed, "a",
goabnf.WithRepMax(15), // Limit repetitions to 15
goabnf.WithThreshold(1024), // Stop ASAP input generation if reached 1024 bytes
)
Function(b)
})
}
```
---
## Troubleshooting
### My ABNF grammar does not work
**Q**: My ABNF grammar does not work. Do you have any idea why ?
**R**: There could be many reasons to this. First make sure your grammar ends up by a newline (LF), and especially that the input content has a CR LF. As those appear the same, it is often a source of error.
### Difference between pap and bap
**Q**: Is there a difference between pap and [bap](https://github.com/ietf-tools/bap) ?
**R**: Yes, first of all the language (i.e. Go) enables more portability thus integration in workflows. But the real difference between pap and bap is the way they work: pap is built on an opportunity to challenge bap whether bap is built to generate meaningfull errors to the end user. Out of this, no, pap and bap are very similar as they are ABNF parsers/validators.