Skip to content

Commit 41a23ea

Browse files
TMHSDigitalclaude
andcommitted
feat(output): -sarif writes takeover candidates for GitHub code scanning
A SARIF 2.1.0 log (validated against the OASIS schema) with one rule per kind of finding (dangling CNAME, dangling at a provider, takeover-prone provider), security severities, the CNAME target in each message and a stable partial fingerprint per name. Monitoring docs show the upload-sarif step. Fixes #129 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 1cbee27 commit 41a23ea

7 files changed

Lines changed: 246 additions & 1 deletion

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [Unreleased]
99

1010
### Added
11+
- `-sarif <file>` writes takeover candidates as a SARIF 2.1.0 log (validated against the OASIS schema): one rule per kind of finding, with a security severity, the CNAME target in the message and a stable fingerprint per name, ready for `github/codeql-action/upload-sarif`. The Monitoring page shows the upload step (#129).
1112
- `-silent` for pipelines: bare result names on stdout and nothing on stderr but errors and a one-line warning when results are simulated. A new [Pipelines](docs/pipelines.md) page chains subenum with dnsx, httpx and nuclei and gates each step on the run-quality verdict (#128).
1213
- A Go library API, `pkg/subenum`, so other programs can embed the engine: `Config` (every zero value takes the CLI's default), `Scan` for a finished run, `Run` to stream `Event` values, and `Result`, `Record` and `Stats`. The DNS internals stay unexported, engine messages name `Config` fields instead of CLI flags, and `Run` always ends with one terminal event carrying the final `Stats`. Runnable examples ship for pkg.go.dev (#77).
1314
- Lab mode: `-simulate-zone <file>` answers every query from a scenario file (names, A/AAAA/CNAME records, wildcards, TIMEOUT/SERVFAIL/REFUSED/NXDOMAIN failures, `$DELAY` and `$REFUSE-ABOVE` rate limiting) through a DNS server on `127.0.0.1`. The real resolver, wildcard detection, `-rate`, takeover hints and the run-quality report run unchanged, deterministically and without traffic leaving the machine. A new [Labs](docs/labs.md) page has five guided exercises with answers, and the scenarios ship in `examples/labs/`. The run-quality report gains a `zone` field (#76).

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -449,6 +449,8 @@ When a result has a CNAME record, subenum resolves the CNAME target with the tru
449449

450450
The marker is a `takeover_candidate` field in JSON and JSONL, a `takeover_candidate` column in CSV, `TAKEOVER?=<marker>` in text with `-show-records`, and a count in the breakdown and the run-quality report. A dangling CNAME makes A/AAAA lookups fail, so scan with CNAME records included to find them: `-type A,AAAA,CNAME`.
451451

452+
`-sarif takeovers.sarif` also writes the candidates as a SARIF 2.1.0 log, one rule per kind of finding and a stable fingerprint per name, so GitHub code scanning can track, triage and dismiss them in the Security tab. Upload it from a scheduled workflow (see [Monitoring](docs/monitoring.md)) with `github/codeql-action/upload-sarif` and `security-events: write`.
453+
452454
> [!IMPORTANT]
453455
> Takeover markers are DNS-only hints. subenum makes no HTTP requests; a `provider:` match is often a perfectly healthy service. Verify every candidate by hand, and only against targets you are authorized to test.
454456

‎docs/_includes/flags.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
| `-recursive` | - | Recursively enumerate subdomains of discovered subdomains |
2424
| `-resume <string>` | - | Resume an interrupted run from its state file (no other arguments) |
2525
| `-retries <int>` | - | Deprecated: use -attempts instead |
26+
| `-sarif <string>` | - | Write takeover candidates to this file as SARIF 2.1.0, for GitHub code scanning (needs CNAME in -type) |
2627
| `-seed <uint>` | - | In simulation mode, seed for reproducible results (0 = random; the seed used is printed) |
2728
| `-seeds <string>` | - | Results file (any -format) whose names also seed -permute; implies -permute |
2829
| `-show-records` | - | In text format, append each result's records (TYPE=value) |

‎internal/output/sarif.go‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
package output
2+
3+
import (
4+
"crypto/sha256"
5+
"encoding/hex"
6+
"encoding/json"
7+
"fmt"
8+
"sort"
9+
"strings"
10+
)
11+
12+
// SARIF (2.1.0) output for takeover candidates (#129), so findings can be
13+
// uploaded to GitHub code scanning (or any SARIF consumer) and tracked,
14+
// triaged and dismissed there. Only names with a takeover hint are results;
15+
// a run with none writes a valid document with no results.
16+
17+
const sarifHelp = "https://tmhsdigital.github.io/subenum/"
18+
19+
type sarifLog struct {
20+
Schema string `json:"$schema"`
21+
Version string `json:"version"`
22+
Runs []sarifRun `json:"runs"`
23+
}
24+
25+
type sarifRun struct {
26+
Tool sarifTool `json:"tool"`
27+
Results []sarifResult `json:"results"`
28+
}
29+
30+
type sarifTool struct {
31+
Driver sarifDriver `json:"driver"`
32+
}
33+
34+
type sarifDriver struct {
35+
Name string `json:"name"`
36+
Version string `json:"version,omitempty"`
37+
InformationURI string `json:"informationUri"`
38+
Rules []sarifRule `json:"rules"`
39+
}
40+
41+
type sarifRule struct {
42+
ID string `json:"id"`
43+
Name string `json:"name"`
44+
ShortDescription sarifText `json:"shortDescription"`
45+
FullDescription sarifText `json:"fullDescription"`
46+
HelpURI string `json:"helpUri"`
47+
DefaultConfiguration sarifRuleLevel `json:"defaultConfiguration"`
48+
Properties sarifRuleProps `json:"properties"`
49+
}
50+
51+
type sarifRuleLevel struct {
52+
Level string `json:"level"`
53+
}
54+
55+
type sarifRuleProps struct {
56+
Tags []string `json:"tags"`
57+
SecuritySeverity string `json:"security-severity"`
58+
}
59+
60+
type sarifText struct {
61+
Text string `json:"text"`
62+
}
63+
64+
type sarifResult struct {
65+
RuleID string `json:"ruleId"`
66+
Level string `json:"level"`
67+
Message sarifText `json:"message"`
68+
Locations []sarifLocation `json:"locations"`
69+
PartialFingerprints map[string]string `json:"partialFingerprints"`
70+
}
71+
72+
type sarifLocation struct {
73+
PhysicalLocation sarifPhysical `json:"physicalLocation"`
74+
}
75+
76+
type sarifPhysical struct {
77+
ArtifactLocation sarifArtifact `json:"artifactLocation"`
78+
}
79+
80+
type sarifArtifact struct {
81+
URI string `json:"uri"`
82+
}
83+
84+
// takeoverRule maps a takeover marker ("dangling", "provider:heroku",
85+
// "dangling:heroku") to its SARIF rule.
86+
func takeoverRule(marker string) sarifRule {
87+
kind, provider, _ := strings.Cut(marker, ":")
88+
r := sarifRule{HelpURI: sarifHelp + "cli.html", Properties: sarifRuleProps{Tags: []string{"security", "subdomain-takeover", "dns"}}}
89+
switch {
90+
case kind == "dangling" && provider == "":
91+
r.ID, r.Name = "subenum/dangling-cname", "DanglingCNAME"
92+
r.ShortDescription.Text = "CNAME points at a name that does not exist"
93+
r.FullDescription.Text = "The subdomain is an alias for a name that returns NXDOMAIN. Whoever registers or claims that name may control the subdomain. Remove the record or reclaim the target."
94+
r.DefaultConfiguration.Level, r.Properties.SecuritySeverity = "error", "7.5"
95+
case kind == "dangling":
96+
r.ID, r.Name = "subenum/dangling-cname/"+provider, "DanglingCNAMEAt"+provider
97+
r.ShortDescription.Text = "CNAME points at an unclaimed " + provider + " name"
98+
r.FullDescription.Text = "The subdomain is an alias for a " + provider + " name that returns NXDOMAIN. " + provider + " lets anyone claim such names, so this is a likely subdomain takeover. Remove the record or reclaim the resource."
99+
r.DefaultConfiguration.Level, r.Properties.SecuritySeverity = "error", "8.6"
100+
default:
101+
r.ID, r.Name = "subenum/takeover-prone-provider/"+provider, "TakeoverProneProvider"+provider
102+
r.ShortDescription.Text = "CNAME points at " + provider + ", a takeover-prone service"
103+
r.FullDescription.Text = "The subdomain is an alias for a " + provider + " resource. It resolves today, but if the resource is deleted while the record stays, anyone can claim it. Keep the record and the resource in the same lifecycle."
104+
r.DefaultConfiguration.Level, r.Properties.SecuritySeverity = "note", "3.0"
105+
}
106+
return r
107+
}
108+
109+
// WriteSARIF writes the takeover candidates among results to path as a
110+
// SARIF 2.1.0 log, atomically. version is the tool version.
111+
func WriteSARIF(path, version string, results []Result) error {
112+
rules := map[string]sarifRule{}
113+
var out []sarifResult
114+
for _, r := range results {
115+
if r.Takeover == "" {
116+
continue
117+
}
118+
rule := takeoverRule(r.Takeover)
119+
rules[rule.ID] = rule
120+
target := ""
121+
for _, rec := range r.Records {
122+
if rec.Type == "CNAME" {
123+
target = strings.TrimSuffix(rec.Value, ".")
124+
}
125+
}
126+
msg := fmt.Sprintf("%s: %s", r.Subdomain, rule.ShortDescription.Text)
127+
if target != "" {
128+
msg = fmt.Sprintf("%s is a CNAME for %s. %s.", r.Subdomain, target, rule.ShortDescription.Text)
129+
}
130+
sum := sha256.Sum256([]byte(r.Subdomain + "\x00" + r.Takeover))
131+
out = append(out, sarifResult{
132+
RuleID: rule.ID,
133+
Level: rule.DefaultConfiguration.Level,
134+
Message: sarifText{Text: msg},
135+
Locations: []sarifLocation{{PhysicalLocation: sarifPhysical{ArtifactLocation: sarifArtifact{URI: r.Subdomain}}}},
136+
PartialFingerprints: map[string]string{"subenumTakeover/v1": hex.EncodeToString(sum[:16])},
137+
})
138+
}
139+
ids := make([]string, 0, len(rules))
140+
for id := range rules {
141+
ids = append(ids, id)
142+
}
143+
sort.Strings(ids)
144+
driver := sarifDriver{Name: "subenum", Version: version, InformationURI: sarifHelp, Rules: []sarifRule{}}
145+
for _, id := range ids {
146+
driver.Rules = append(driver.Rules, rules[id])
147+
}
148+
if out == nil {
149+
out = []sarifResult{}
150+
}
151+
doc := sarifLog{
152+
Schema: "https://json.schemastore.org/sarif-2.1.0.json",
153+
Version: "2.1.0",
154+
Runs: []sarifRun{{Tool: sarifTool{Driver: driver}, Results: out}},
155+
}
156+
data, err := json.MarshalIndent(doc, "", " ")
157+
if err != nil {
158+
return err
159+
}
160+
f, err := CreateFile(path)
161+
if err != nil {
162+
return err
163+
}
164+
_, werr := f.Write(append(data, '\n'))
165+
if cerr := f.Close(werr == nil); werr == nil {
166+
werr = cerr
167+
}
168+
return werr
169+
}

‎main.go‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,7 @@ type cliFlags struct {
143143
noAbort bool
144144
maxQueries int
145145
statsFile string
146+
sarifFile string // -sarif: takeover candidates as SARIF (#129)
146147
exclude string
147148
excludeFile string
148149
resolvers string // -r: file of resolver addresses for a pool
@@ -197,6 +198,7 @@ func parseFlagsWith(args []string, applyDefaults func(*flag.FlagSet) error) (cli
197198
fs.BoolVar(&f.noAbort, "no-abort", false, "Do not abort when the resolver failure rate exceeds 20% (warning is still emitted)")
198199
fs.IntVar(&f.maxQueries, "max-queries", 0, "Max candidate names to test (0 = unlimited); each name sends one query per record type, per attempt")
199200
fs.StringVar(&f.statsFile, "stats", "", "Write a JSON run-quality report (outcomes, queries sent, verdict) to this file")
201+
fs.StringVar(&f.sarifFile, "sarif", "", "Write takeover candidates to this file as SARIF 2.1.0, for GitHub code scanning (needs CNAME in -type)")
200202
fs.StringVar(&f.exclude, "exclude", "", "Comma-separated out-of-scope names and *.parent patterns; never queried or expanded")
201203
fs.StringVar(&f.excludeFile, "exclude-file", "", "File of out-of-scope names and *.parent patterns, one per line (# comments allowed)")
202204
fs.BoolVar(&f.permute, "permute", false, "After each scan, scan permutations of the names found (api -> api-dev, dev-api, dev.api, api2, ...)")
@@ -600,6 +602,9 @@ func run() (code int) {
600602
out.Error("%v", typesErr)
601603
return exitUsage
602604
}
605+
if f.sarifFile != "" && !slices.Contains(recordTypes, "CNAME") {
606+
out.Info("Note: -sarif lists takeover candidates, which need CNAME lookups; add -type A,AAAA,CNAME")
607+
}
603608
if err != nil {
604609
out.Error("%v", err)
605610
return exitUsage
@@ -744,13 +749,17 @@ func run() (code int) {
744749
w.SetTakeoverColumn(slices.Contains(recordTypes, "CNAME"))
745750
}
746751
var targetResults []output.Result // the current target's results: -permute seeds, saved on interrupt
752+
var takeovers []output.Result // every target's takeover candidates, for -sarif
747753
restored := map[string]bool{} // names re-emitted from a -resume state
748754
emitResult := func(ev scan.Event, permutation bool) {
749755
if restored[ev.Domain] {
750756
return
751757
}
752758
res := output.Result{Subdomain: ev.Domain, Records: ev.Records, Takeover: ev.Takeover, Permutation: permutation}
753759
targetResults = append(targetResults, res)
760+
if res.Takeover != "" {
761+
takeovers = append(takeovers, res)
762+
}
754763
if diff == nil {
755764
out.Emit(res)
756765
return
@@ -997,6 +1006,12 @@ func run() (code int) {
9971006
fileErrReported = true
9981007
}
9991008
}
1009+
if f.sarifFile != "" && anyDone {
1010+
if err := output.WriteSARIF(f.sarifFile, resolveVersion(), takeovers); err != nil {
1011+
out.Error("writing -sarif file: %v", err)
1012+
fileErrReported = true
1013+
}
1014+
}
10001015
if anyDone {
10011016
if fileOut != nil {
10021017
if err := fileOut.Finish(); err != nil {

‎main_completion.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ import (
1919
// test fails when a flag whose usage mentions a file is missing here (#117).
2020
var fileFlags = map[string]bool{
2121
"w": true, "dL": true, "o": true, "stats": true, "diff": true, "r": true, "exclude-file": true,
22-
"simulate-zone": true, "seeds": true, "resume": true, "state": true,
22+
"simulate-zone": true, "seeds": true, "resume": true, "state": true, "sarif": true,
2323
}
2424

2525
// completionShells are the shells `subenum completion` writes scripts for.

‎main_lab_test.go‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,3 +169,60 @@ func TestE2ELabRefusesEnvAndConfigResolvers(t *testing.T) {
169169
})
170170
}
171171
}
172+
173+
// TestE2ESARIF covers #129: lab 1's dangling CNAME becomes a SARIF result
174+
// with a rule, a location and a stable fingerprint.
175+
func TestE2ESARIF(t *testing.T) {
176+
zone := filepath.Join("examples", "labs", "lab1-first-scan.zone")
177+
path := filepath.Join(t.TempDir(), "takeovers.sarif")
178+
if code, _ := runCLI(t, "", "-progress=false", "-type", "A,CNAME", "-sarif", path, "-simulate-zone", zone, "lab.example"); code != 0 {
179+
t.Fatalf("exit %d", code)
180+
}
181+
data, err := os.ReadFile(path)
182+
if err != nil {
183+
t.Fatal(err)
184+
}
185+
var log struct {
186+
Version string `json:"version"`
187+
Runs []struct {
188+
Tool struct {
189+
Driver struct {
190+
Name string `json:"name"`
191+
Rules []struct {
192+
ID string `json:"id"`
193+
} `json:"rules"`
194+
} `json:"driver"`
195+
} `json:"tool"`
196+
Results []struct {
197+
RuleID string `json:"ruleId"`
198+
Message struct{ Text string } `json:"message"`
199+
Locations []struct {
200+
PhysicalLocation struct {
201+
ArtifactLocation struct{ URI string } `json:"artifactLocation"`
202+
} `json:"physicalLocation"`
203+
} `json:"locations"`
204+
PartialFingerprints map[string]string `json:"partialFingerprints"`
205+
} `json:"results"`
206+
} `json:"runs"`
207+
}
208+
if err := json.Unmarshal(data, &log); err != nil {
209+
t.Fatal(err)
210+
}
211+
if log.Version != "2.1.0" || len(log.Runs) != 1 || log.Runs[0].Tool.Driver.Name != "subenum" {
212+
t.Fatalf("not a SARIF 2.1.0 subenum log:\n%s", data)
213+
}
214+
run := log.Runs[0]
215+
if len(run.Results) != 1 {
216+
t.Fatalf("got %d results, want lab 1's one dangling CNAME:\n%s", len(run.Results), data)
217+
}
218+
r := run.Results[0]
219+
if r.RuleID != "subenum/dangling-cname" || len(run.Tool.Driver.Rules) != 1 || run.Tool.Driver.Rules[0].ID != r.RuleID {
220+
t.Errorf("rule %q, rules %+v", r.RuleID, run.Tool.Driver.Rules)
221+
}
222+
if len(r.Locations) != 1 || r.Locations[0].PhysicalLocation.ArtifactLocation.URI != "blog.lab.example" || r.PartialFingerprints["subenumTakeover/v1"] == "" {
223+
t.Errorf("result = %+v", r)
224+
}
225+
if !strings.Contains(r.Message.Text, "ghost-lab.example.net") {
226+
t.Errorf("message %q does not name the CNAME target", r.Message.Text)
227+
}
228+
}

0 commit comments

Comments
 (0)