spftrace 0.0.4

Utility for tracing SPF queries
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

# spftrace

The **spftrace** utility is a tool for executing, analysing, and displaying SPF
queries. SPF is specified in [RFC 7208].

This utility executes an SPF query with IP address and domain and shows the
result graphically as an evaluation tree.

This utility uses the [viaspf] library to execute SPF queries. The viaspf
library can trace a query as it executes and makes the trace available as
structured data in its API. spftrace then analyses this data and displays it.

Thanks to the underlying execution engine being a real, RFC-conformant SPF
implementation, spftrace handles all SPF policies correctly. Less well-known
features of SPF such as macros, dual CIDR prefix lengths, *exp* modifiers, or
the void lookup limit are all evaluated according to spec.

[RFC 7208]: https://www.rfc-editor.org/rfc/rfc7208
[viaspf]: https://crates.io/crates/viaspf

## Installation

The spftrace utility is a [Rust] program. Install it with Cargo as usual:

```
cargo install --locked spftrace
```

The minimum supported Rust version is 1.56.1.

[Rust]: https://www.rust-lang.org

## Usage

Pass a sender identity (an email address or a domain name) and an IP address to
spftrace.

Use the unspecified IP address `0.0.0.0` or `::` to display the full evaluation
tree of some SPF-enabled domain.

```
spftrace example.com 0.0.0.0
```

```
example.com
│   "v=spf1 mx include:spf.example.com ~all"
├── mx → example.com (lookups: 1/10, nested: 2/10)
│   ├── mx1.example.com
│   │   ├── 216.58.192.0
│   │   ├── 65.55.52.224
│   │   └── 207.46.116.128
│   └── mx2.example.com
│       └── 65.55.238.129
│   not-match
├── include:spf.example.com → spf.example.com (lookups: 2/10)
│   spf.example.com
│   │   "v=spf1 ip4:207.46.4.128/25 ip4:65.55.174.0/24 ip6:2c0f:fb50:4000::/36
│   │    ip6:2001:4860:4000::/36 ~all"
│   ├── ip4:207.46.4.128/25 not-match
│   ├── ip4:65.55.174.0/24 not-match
│   ├── ip6:2c0f:fb50:4000::/36 not-match
│   ├── ip6:2001:4860:4000::/36 not-match
│   └── all match result=softfail
│   not-match
└── all match result=softfail
softfail
```

For details, refer to the included man page *spftrace*(1). (You can view the man
page without installing by passing the file path to `man`: `man ./spftrace.1`)

## Development

Unit tests are in separate module `tests`. Specify a test name and pass the
`--show-output` test binary option to run and visually check some test. For
example:

```
cargo test ptr -- --show-output
```

## Licence

Copyright © 2022 David Bürgin

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.