api-mode.md

api mode

use sif's json output for automation and integration.

enabling api mode

./sif -u https://example.com -api

output format

api mode outputs json to stdout:

{
  "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

./sif -u https://example.com -api -am > results.json

pipe to jq

./sif -u https://example.com -api -am | jq '.results[].data.findings[]'

filter high severity

./sif -u https://example.com -api -am | jq '.results[].data.findings[] | select(.severity == "high")'

extract urls

./sif -u https://example.com -api -am | jq -r '.results[].data.findings[].url'

ci/cd integration

github actions

- 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

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:

./sif -u https://site1.com,https://site2.com -api

outputs:

{"url":"https://site1.com","results":[...]}
{"url":"https://site2.com","results":[...]}

use jq -s to combine into an array:

./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