gitea-mirror/sif
1
0
Fork 0
mirror of https://github.com/lunchcat/sif.git synced 2026-01-14 13:56:37 -08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add comprehensive documentation and fix github actions

Browse Source 
- add docs/ with installation, usage, modules, scans, and api docs
- add docs link to main readme
- fix release.yml to bundle modules directory with releases
- add module system tests to runtest.yml
- standardize go version to 1.23 across workflows
This commit is contained in:
Celeste Hickenlooper
2026-01-03 03:39:58 -08:00
parent c7598a1d3f
commit 4942425ce5
12 changed files with 1330 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/README.md Normal file
View File

@@ -0,0 +1,52 @@
# sif documentation
welcome to the sif documentation. sif is a modular pentesting toolkit designed to be fast, concurrent, and extensible.
## table of contents
### getting started
- [installation](installation.md) - how to install sif
- [quickstart](quickstart.md) - get up and running in minutes
- [usage](usage.md) - command line options and examples
### features
- [scans](scans.md) - built-in security scans
- [modules](modules.md) - yaml module system and custom modules
### reference
- [configuration](configuration.md) - runtime configuration options
- [api mode](api-mode.md) - json output for automation
### contributing
- [development](development.md) - setting up a dev environment
- [writing modules](modules.md#writing-modules) - create your own modules
---
## quick links
```bash
# install
git clone https://github.com/dropalldatabases/sif.git && cd sif && make
# basic scan
./sif -u https://example.com
# list modules
./sif -lm
# run all modules
./sif -u https://example.com -am
# help
./sif -h
```
## support
- [github issues](https://github.com/vmfunc/sif/issues) - bug reports and feature requests
- [discord](https://discord.gg/sifcli) - community chat

160
docs/api-mode.md Normal file
View File

@@ -0,0 +1,160 @@
# api mode
use sif's json output for automation and integration.
## enabling api mode
```bash
./sif -u https://example.com -api
```
## output format
api mode outputs json to stdout:
```json
{
"url": "https://example.com",
"results": [
{
"id": "module-id",
"data": {
"module_id": "module-id",
"target": "https://example.com",
"findings": [
{
"url": "https://example.com/.git/HEAD",
"severity": "high",
"evidence": "ref: refs/heads/main",
"extracted": {
"branch": "main"
}
}
]
}
}
]
}
```
## fields
### url
the target url that was scanned.
### results
array of module results.
### results[].id
module identifier.
### results[].data.findings
array of security findings from the module.
### findings[].url
the specific url where the finding was detected.
### findings[].severity
severity level: `info`, `low`, `medium`, `high`, `critical`
### findings[].evidence
evidence that triggered the finding (matched content, etc).
### findings[].extracted
extracted data from the response (versions, keys, etc).
## examples
### save to file
```bash
./sif -u https://example.com -api -am > results.json
```
### pipe to jq
```bash
./sif -u https://example.com -api -am | jq '.results[].data.findings[]'
```
### filter high severity
```bash
./sif -u https://example.com -api -am | jq '.results[].data.findings[] | select(.severity == "high")'
```
### extract urls
```bash
./sif -u https://example.com -api -am | jq -r '.results[].data.findings[].url'
```
## ci/cd integration
### github actions
```yaml
- name: run sif scan
run: |
./sif -u ${{ env.TARGET_URL }} -api -am > sif-results.json
- name: check for high severity findings
run: |
HIGH_COUNT=$(jq '[.results[].data.findings[] | select(.severity == "high" or .severity == "critical")] | length' sif-results.json)
if [ "$HIGH_COUNT" -gt 0 ]; then
echo "Found $HIGH_COUNT high/critical severity findings"
exit 1
fi
```
### gitlab ci
```yaml
security_scan:
script:
- ./sif -u $TARGET_URL -api -am > sif-results.json
- |
if jq -e '.results[].data.findings[] | select(.severity == "critical")' sif-results.json > /dev/null; then
echo "Critical findings detected"
exit 1
fi
artifacts:
paths:
- sif-results.json
```
## multiple targets
when scanning multiple urls, each target outputs a separate json object:
```bash
./sif -u https://site1.com,https://site2.com -api
```
outputs:
```json
{"url":"https://site1.com","results":[...]}
{"url":"https://site2.com","results":[...]}
```
use `jq -s` to combine into an array:
```bash
./sif -u https://site1.com,https://site2.com -api | jq -s '.'
```
## notes
- api mode suppresses banner and interactive output
- all output goes to stdout
- errors and warnings still go to stderr
- combine with `-l` flag to also save detailed logs

162
docs/configuration.md Normal file
View File

@@ -0,0 +1,162 @@
# configuration
runtime configuration options for sif.
## environment variables
### SHODAN_API_KEY
required for shodan lookups.
```bash
export SHODAN_API_KEY=your-api-key-here
./sif -u https://example.com -shodan
```
## command line options
### timeout
default request timeout is 10 seconds.
```bash
# increase for slow targets
./sif -u https://example.com -t 30s
# decrease for fast scans
./sif -u https://example.com -t 5s
```
### threads
default is 10 concurrent threads.
```bash
# more threads for faster scanning
./sif -u https://example.com --threads 50
# fewer threads to reduce load
./sif -u https://example.com --threads 5
```
### logging
save output to files:
```bash
./sif -u https://example.com -l ./logs
```
creates timestamped log files in the specified directory.
### debug mode
enable verbose logging:
```bash
./sif -u https://example.com -d
```
## user modules
place custom modules in:
- linux/macos: `~/.config/sif/modules/`
- windows: `%LOCALAPPDATA%\sif\modules\`
### directory structure
```
~/.config/sif/
├── modules/
│ ├── http/
│ │ └── my-sqli-check.yaml
│ ├── recon/
│ │ └── custom-paths.yaml
│ └── my-module.yaml
```
modules can be organized in subdirectories or placed directly in the modules folder.
### overriding built-in modules
user modules with the same id as built-in modules will override them:
```yaml
# ~/.config/sif/modules/sqli-error-based.yaml
# this overrides the built-in sqli-error-based module
id: sqli-error-based
info:
name: my custom sqli check
# ...
```
## performance tuning
### fast scans
```bash
./sif -u https://example.com \
--threads 50 \
-t 5s \
-dirlist small \
-dnslist small
```
### thorough scans
```bash
./sif -u https://example.com \
--threads 10 \
-t 30s \
-dirlist large \
-dnslist large \
-ports full
```
### low-impact scans
reduce load on target:
```bash
./sif -u https://example.com \
--threads 2 \
-t 10s
```
## output formats
### console (default)
human-readable output with colors and formatting.
### json (api mode)
```bash
./sif -u https://example.com -api
```
returns structured json:
```json
{
"url": "https://example.com",
"results": [
{
"id": "sqli-error-based",
"data": {
"findings": [...]
}
}
]
}
```
### log files
```bash
./sif -u https://example.com -l ./logs
```
creates separate log files for each scan type.

185
docs/development.md Normal file
View File

@@ -0,0 +1,185 @@
# development
setting up a development environment for sif.
## prerequisites
- go 1.23 or later
- git
- make
## clone and build
```bash
git clone https://github.com/dropalldatabases/sif.git
cd sif
make
```
## project structure
```
sif/
├── cmd/sif/ # entry point
│ └── main.go
├── sif.go # main application logic
├── internal/ # private packages
│ ├── config/ # configuration parsing
│ ├── logger/ # logging utilities
│ ├── modules/ # module system
│ ├── scan/ # built-in scans
│ ├── styles/ # terminal styling
│ └── worker/ # worker pool
├── modules/ # built-in yaml modules
│ ├── http/ # http-based modules
│ ├── info/ # information gathering
│ └── recon/ # reconnaissance modules
├── docs/ # documentation
└── assets/ # images, etc
```
## running locally
```bash
# build
make
# run
./sif -u https://example.com
# run with debug
./sif -u https://example.com -d
```
## code quality
### format
```bash
gofmt -w .
```
### lint
```bash
golangci-lint run
```
### test
```bash
go test ./...
```
### race detection
```bash
go test -race ./...
```
## adding a new scan
1. create a new file in `internal/scan/`
2. implement the scan function
3. add flag to `internal/config/config.go`
4. integrate in `sif.go`
see existing scans for examples.
## adding a new module
create a yaml file in `modules/`:
```yaml
id: my-new-module
info:
name: my new security check
author: your-name
severity: medium
description: what this checks for
tags: [custom, security]
type: http
http:
method: GET
paths:
- "{{BaseURL}}/path"
matchers:
- type: status
status:
- 200
```
see [modules.md](modules.md) for the full format.
## module system internals
the module system is in `internal/modules/`:
- `module.go` - core interface and types
- `registry.go` - module registration
- `loader.go` - discovery and loading
- `yaml.go` - yaml parsing
- `executor.go` - http execution
### adding a new module type
1. add type constant to `module.go`
2. implement executor in new file
3. update loader to handle new extension/type
## testing
### unit tests
```bash
go test ./internal/...
```
### functional test
```bash
./sif -u https://example.com -am
```
### test modules
```bash
./sif -lm # list modules
./sif -u https://example.com -m my-module -d # test specific module
```
## pull requests
1. fork the repository
2. create a feature branch
3. make changes
4. run `gofmt -w .` and `golangci-lint run`
5. submit pr
### commit messages
use lowercase, present tense:
```
add sql injection module
fix timeout handling in http executor
update readme with new flags
```
## release process
releases are automated via github actions on push to main.
binaries are built for:
- linux (amd64, 386, arm64)
- macos (amd64, arm64)
- windows (amd64, 386)
## resources
- [go documentation](https://golang.org/doc/)
- [goflags](https://github.com/projectdiscovery/goflags) - cli parsing
- [nuclei templates](https://github.com/projectdiscovery/nuclei-templates) - module format inspiration

93
docs/installation.md Normal file
View File

@@ -0,0 +1,93 @@
# installation
## from releases
download the latest binary for your platform from [releases](https://github.com/vmfunc/sif/releases).
### linux
```bash
# download
curl -LO https://github.com/vmfunc/sif/releases/latest/download/sif-linux-amd64
# make executable
chmod +x sif-linux-amd64
# move to path (optional)
sudo mv sif-linux-amd64 /usr/local/bin/sif
```
### macos
```bash
# intel
curl -LO https://github.com/vmfunc/sif/releases/latest/download/sif-macos-amd64
# apple silicon
curl -LO https://github.com/vmfunc/sif/releases/latest/download/sif-macos-arm64
chmod +x sif-macos-*
sudo mv sif-macos-* /usr/local/bin/sif
```
### windows
download `sif-windows-amd64.exe` from releases and add to your PATH.
## from source
requires go 1.23+
```bash
git clone https://github.com/dropalldatabases/sif.git
cd sif
make
```
the binary will be created in the current directory.
### install to system
```bash
sudo make install
```
this installs to `/usr/local/bin/sif`.
### uninstall
```bash
sudo make uninstall
```
## verify installation
```bash
./sif -h
```
you should see the help output with available flags.
## updating
### from releases
download the new binary and replace the old one.
### from source
```bash
cd sif
git pull
make clean
make
```
## modules directory
sif looks for modules in these locations:
- **built-in**: `modules/` directory next to the sif binary
- **user modules**: `~/.config/sif/modules/` (linux/macos) or `%LOCALAPPDATA%\sif\modules\` (windows)
user modules override built-in modules with the same id.

102
docs/quickstart.md Normal file
View File

@@ -0,0 +1,102 @@
# quickstart
get up and running with sif in minutes.
## basic scan
run a basic scan against a target:
```bash
./sif -u https://example.com
```
this performs a base scan checking robots.txt, common files, and basic reconnaissance.
## add more scans
enable additional scan types with flags:
```bash
# directory fuzzing
./sif -u https://example.com -dirlist medium
# subdomain enumeration
./sif -u https://example.com -dnslist small
# port scanning
./sif -u https://example.com -ports common
# framework detection
./sif -u https://example.com -framework
```
## run modules
sif has a modular architecture with yaml-based security checks:
```bash
# list available modules
./sif -lm
# run all modules
./sif -u https://example.com -am
# run specific modules
./sif -u https://example.com -m sqli-error-based,xss-reflected
# run by tag
./sif -u https://example.com -mt owasp-top10
```
## multiple targets
scan multiple urls:
```bash
./sif -u https://site1.com,https://site2.com
```
or from a file:
```bash
./sif -f targets.txt
```
## save output
save results to a log directory:
```bash
./sif -u https://example.com -l ./logs
```
## json output
for automation, use api mode:
```bash
./sif -u https://example.com -api
```
## full scan example
run everything:
```bash
./sif -u https://example.com \
-dirlist medium \
-dnslist small \
-ports common \
-framework \
-js \
-headers \
-git \
-am \
-l ./logs
```
## next steps
- [usage](usage.md) - all command line options
- [scans](scans.md) - detailed scan descriptions
- [modules](modules.md) - write custom modules

228
docs/scans.md Normal file
View File

@@ -0,0 +1,228 @@
# scans
detailed information about sif's built-in security scans.
## base scan
runs automatically unless `-noscan` is specified.
checks:
- robots.txt parsing
- common files (sitemap.xml, security.txt, etc)
- basic reconnaissance
## directory fuzzing (-dirlist)
brute-forces directories and files using wordlists.
### sizes
| size | entries | use case |
|------|---------|----------|
| small | ~1k | quick scan, low noise |
| medium | ~10k | balanced coverage |
| large | ~100k | thorough, takes longer |
### what it finds
- hidden directories (/admin, /backup, /config)
- backup files (.bak, .old, .zip)
- configuration files
- development artifacts
## subdomain enumeration (-dnslist)
discovers subdomains via dns brute-forcing.
### sizes
| size | entries | use case |
|------|---------|----------|
| small | ~1k | quick discovery |
| medium | ~10k | common subdomains |
| large | ~100k | comprehensive |
### what it finds
- dev/staging environments
- internal services
- forgotten subdomains
- api endpoints
## port scanning (-ports)
scans for open ports and identifies services.
### scopes
| scope | ports | description |
|-------|-------|-------------|
| common | top 1000 | most common services |
| full | 1-65535 | all ports, slow |
### what it finds
- web servers (80, 443, 8080)
- databases (3306, 5432, 27017)
- admin interfaces (8443, 9090)
- development servers
## framework detection (-framework)
identifies web frameworks and their versions.
### detects
- react, vue, angular, next.js
- django, flask, rails
- laravel, symfony, express
- wordpress, drupal, joomla
### features
- version detection
- cve lookup for known vulnerabilities
- confidence scoring
## javascript analysis (-js)
analyzes javascript files for security issues.
### finds
- api endpoints and keys
- hardcoded credentials
- internal urls
- framework configurations
- source maps
## http headers (-headers)
analyzes security headers.
### checks
- content-security-policy
- x-frame-options
- x-content-type-options
- strict-transport-security
- x-xss-protection
- permissions-policy
## cms detection (-cms)
identifies content management systems.
### detects
- wordpress (with version)
- drupal
- joomla
- magento
- shopify
- ghost
## git repository (-git)
checks for exposed git repositories.
### finds
- .git/HEAD
- .git/config
- .git/index
- source code exposure risk
## cloud storage (-c3)
checks for cloud storage misconfigurations.
### checks
- s3 bucket access
- azure blob storage
- gcp storage buckets
- open bucket policies
## subdomain takeover (-st)
detects subdomain takeover vulnerabilities.
requires `-dnslist` to enumerate subdomains first.
### checks
- dangling cname records
- unclaimed cloud services
- expired third-party services
## shodan lookup (-shodan)
queries shodan for host intelligence.
requires `SHODAN_API_KEY` environment variable.
### returns
- open ports
- services and versions
- known vulnerabilities
- ssl/tls info
- organization data
## sql reconnaissance (-sql)
detects sql-related exposures.
### finds
- admin panels (/phpmyadmin, /adminer)
- database error messages
- sql injection indicators
## lfi scanning (-lfi)
checks for local file inclusion vulnerabilities.
### tests
- path traversal (../)
- null byte injection
- common lfi payloads
- sensitive file disclosure
## whois lookup (-whois)
performs whois lookups on target domains.
### returns
- registrar info
- creation/expiration dates
- nameservers
- registrant info (if available)
## google dorking (-dork)
automated google dorking for target.
### searches
- indexed sensitive files
- exposed admin panels
- configuration files
- backup files
- error pages
## nuclei scanning (-nuclei)
runs nuclei vulnerability templates.
requires nuclei to be installed.
### templates
- cve detection
- misconfigurations
- exposures
- default credentials

293
docs/usage.md Normal file
View File

@@ -0,0 +1,293 @@
# usage
complete guide to sif command line options.
## target options
### -u, --urls
specify target urls (comma-separated):
```bash
./sif -u https://example.com
./sif -u https://site1.com,https://site2.com
```
### -f, --file
read targets from a file (one url per line):
```bash
./sif -f targets.txt
```
## scan options
### directory fuzzing
`-dirlist <size>` - fuzz for directories and files
sizes: `small`, `medium`, `large`
```bash
./sif -u https://example.com -dirlist medium
```
### subdomain enumeration
`-dnslist <size>` - enumerate subdomains
sizes: `small`, `medium`, `large`
```bash
./sif -u https://example.com -dnslist small
```
### port scanning
`-ports <scope>` - scan for open ports
scopes: `common` (top ports), `full` (all ports)
```bash
./sif -u https://example.com -ports common
```
### google dorking
`-dork` - automated google dorking
```bash
./sif -u https://example.com -dork
```
### git repository detection
`-git` - check for exposed git repositories
```bash
./sif -u https://example.com -git
```
### nuclei scanning
`-nuclei` - run nuclei vulnerability templates
```bash
./sif -u https://example.com -nuclei
```
### javascript analysis
`-js` - analyze javascript files
```bash
./sif -u https://example.com -js
```
### cms detection
`-cms` - detect content management systems
```bash
./sif -u https://example.com -cms
```
### http headers
`-headers` - analyze security headers
```bash
./sif -u https://example.com -headers
```
### cloud storage
`-c3` - check for cloud storage misconfigurations
```bash
./sif -u https://example.com -c3
```
### subdomain takeover
`-st` - check for subdomain takeover vulnerabilities
requires `-dnslist` to be enabled
```bash
./sif -u https://example.com -dnslist small -st
```
### shodan lookup
`-shodan` - query shodan for host intelligence
requires `SHODAN_API_KEY` environment variable
```bash
export SHODAN_API_KEY=your-api-key
./sif -u https://example.com -shodan
```
### sql reconnaissance
`-sql` - detect sql admin panels and error disclosure
```bash
./sif -u https://example.com -sql
```
### lfi scanning
`-lfi` - local file inclusion vulnerability checks
```bash
./sif -u https://example.com -lfi
```
### framework detection
`-framework` - detect web frameworks with version and cve lookup
```bash
./sif -u https://example.com -framework
```
### whois lookup
`-whois` - perform whois lookups
```bash
./sif -u https://example.com -whois
```
### skip base scan
`-noscan` - skip the base url scan (robots.txt, etc)
```bash
./sif -u https://example.com -noscan -dirlist medium
```
## module options
### -lm, --list-modules
list all available modules:
```bash
./sif -lm
```
### -m, --modules
run specific modules by id (comma-separated):
```bash
./sif -u https://example.com -m sqli-error-based,xss-reflected
```
### -mt, --module-tags
run modules matching tags:
```bash
./sif -u https://example.com -mt owasp-top10
./sif -u https://example.com -mt injection
```
### -am, --all-modules
run all available modules:
```bash
./sif -u https://example.com -am
```
## runtime options
### -t, --timeout
http request timeout (default: 10s):
```bash
./sif -u https://example.com -t 30s
```
### --threads
number of concurrent threads (default: 10):
```bash
./sif -u https://example.com --threads 20
```
### -l, --log
directory to save log files:
```bash
./sif -u https://example.com -l ./logs
```
### -d, --debug
enable debug logging:
```bash
./sif -u https://example.com -d
```
## api options
### -api
enable api mode for json output:
```bash
./sif -u https://example.com -api
```
output is a json object with scan results.
## examples
### quick recon
```bash
./sif -u https://example.com -framework -headers -git
```
### full scan
```bash
./sif -u https://example.com \
-dirlist large \
-dnslist medium \
-ports full \
-framework \
-js \
-headers \
-cms \
-git \
-sql \
-lfi \
-am
```
### ci/cd pipeline
```bash
./sif -u https://staging.example.com -api -am > results.json
```
### batch scanning
```bash
echo "https://site1.com
https://site2.com
https://site3.com" > targets.txt
./sif -f targets.txt -am -l ./logs
```