sif/CONTRIBUTING.md

Contributing

Thank you for taking the time to contribute to sif! All contributions are valued, and no contribution is too small or insignificant. If you want to contribute but don't know where to start, worry not; there is no shortage of things to do.
Even if you don't know any Go, don't let that stop you from trying to contribute! We're here to help.

By contributing to this repository, you agree to adhere to the sif Code of Conduct. Not doing so may result in a ban.

How can I help?

Here are some ways to get started:

• Have a look at our issue tracker.
• If you've encountered a bug, discuss it with us, report it.
• Once you've found a bug you believe you can fix, open a pull request for it.
• Alternatively, consider packaging sif for your distribution.

If you like the project, but don't have time to contribute, that's okay too! Here are other ways to show your appreciation for the project:

• Use sif (seriously, that's enough)
• Star the repository
• Share sif with your friends
• Support us on Liberapay (thank you!)

Reporting issues

If you believe you've found a bug, or you have a new feature to request, please hop on the Discord server first to discuss it.
This way, if it's an easy fix, we could help you solve it more quickly, and if it's a feature request we could workshop it together into something more mature.

When opening an issue, please use the search tool and make sure that the issue has not been discussed before. In the case of a bug report, run sif with the -d/-debug flag for full debug logs.

Contributing code

Development

To develop sif, you'll need version 1.23 or later of the Go toolchain. After making your changes, run the program using go run ./cmd/sif to make sure it compiles and runs properly.

Nix users: the repository provides a flake that can be used to develop and run sif. Use nix run, nix develop, nix build, etc. Make sure to run gomod2nix if go.mod is changed.

Submitting a pull request

When making a pull request, please adhere to the following conventions:

• sif adheres to the Go style guidelines. Always format your gode with gofmt.
• When adding/removing imports, make sure to use go mod tidy, and then run gomod2nix to generate the Nix-readable module list.
• Set git config pull.rebase true to rebase commits on pull instead of creating ugly merge commits.
• Title your commits in present tense, in the imperative style.
  • You may use prefixes like feat, fix, chore, deps, etc.
    Example: deps: update gopkg.in/yaml.v3 to v3.0.1
  • You may use prefixes to denote the part of the code changed in the commit.
    Example: pkg/scan: ignore 3xx redirects
  • If not using a prefix, make sure to use sentence case.
    Example: Add nuclei template parsing support
  • If applicable, provide a helpful commit description, listing usage notes, implementation details, and tasks that still need to be done.

If you have any questions, feel free to ask around on the IRC channel.

Contributing Framework Detection Patterns

The framework detection module (internal/scan/frameworks/) identifies web frameworks by analyzing HTTP headers and response bodies. Detectors are organized by category in the detectors/ subdirectory:

Adding a New Framework Detector

1. Create a detector struct in the appropriate file in detectors/:

// myframeworkDetector detects MyFramework.
type myframeworkDetector struct{}

func (d *myframeworkDetector) Name() string { return "MyFramework" }

func (d *myframeworkDetector) Signatures() []fw.Signature {
    return []fw.Signature{
        {Pattern: "unique-identifier", Weight: 0.5},
        {Pattern: "header-signature", Weight: 0.4, HeaderOnly: true},
        {Pattern: "body-signature", Weight: 0.3},
    }
}

...

2. Register the detector in the init() function of the same file:

func init() {
    fw.Register(&myframeworkDetector{})
}

Pattern Guidelines:

• Weight: How much this signature contributes to detection (0.0-1.0)
• HeaderOnly: Set to true for HTTP header patterns
• Use unique identifiers that won't false-positive on other frameworks
• Include multiple patterns for higher confidence

Adding Version Detection

Add version patterns to version.go in the rawPatterns map inside init():

"MyFramework": {
    {`<meta name="generator" content="MyFramework v?(\d+\.\d+(?:\.\d+)?)"`, 0.95, "generator meta"},
    {`MyFramework[/\s]+[Vv]?(\d+\.\d+(?:\.\d+)?)`, 0.9, "explicit version"},
    {`"myframework":\s*"[~^]?(\d+\.\d+(?:\.\d+)?)"`, 0.85, "package.json"},
},

Adding CVE Data

Add known vulnerabilities to cve.go in the knownCVEs map:

"MyFramework": {
    {
        CVE:              "CVE-YYYY-XXXXX",
        AffectedVersions: []string{"1.0.0", "1.0.1", "1.1.0"},
        FixedVersion:     "1.2.0",
        Severity:         "high",  // critical, high, medium, low
        Description:      "Brief description of the vulnerability",
        Recommendations:  []string{"Update to 1.2.0 or later"},
    },
},

Testing Your Changes

Always add tests for new frameworks in detect_test.go:

func TestDetectFramework_MyFramework(t *testing.T) {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
        w.Write([]byte(`<html><body>unique-identifier</body></html>`))
    }))
    defer server.Close()

    result, err := frameworks.DetectFramework(server.URL, 5*time.Second, "")
    // assertions...
}

Also add your framework to the registry test in TestDetectorRegistry:

expectedDetectors := []string{"Laravel", "Django", ..., "MyFramework"}

Future Enhancements (Help Wanted)

• Custom Signature Support: Allow users to define signatures via config file
• CVE API Integration: Real-time CVE data from NVD or other sources
• Automated Signature Updates: Fetch new signatures from a central repository
• Framework Fingerprint Database: Community-maintained signature database

Configuration

Framework Detection Flags

Flag	Description
-framework	Enable framework detection
-timeout	HTTP request timeout (affects all modules)
-threads	Number of concurrent workers
-log	Directory to save scan results
-debug	Enable debug logging for verbose output

Environment Variables

Variable	Description
SHODAN_API_KEY	API key for Shodan host intelligence

Packaging

We'd love it if you helped us bring sif to your distribution. The repository provides a Makefile for building and packaging sif for any distro; consult your distribution's documentation for details.