mirror of
https://github.com/lunchcat/sif.git
synced 2026-01-11 12:35:37 -08:00
4942425ce5
- 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
161 lines
2.9 KiB
Markdown
161 lines
2.9 KiB
Markdown
# 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
|