|
| 1 | +# api mode |
| 2 | + |
| 3 | +use sif's json output for automation and integration. |
| 4 | + |
| 5 | +## enabling api mode |
| 6 | + |
| 7 | +```bash |
| 8 | +./sif -u https://example.com -api |
| 9 | +``` |
| 10 | + |
| 11 | +## output format |
| 12 | + |
| 13 | +api mode outputs json to stdout: |
| 14 | + |
| 15 | +```json |
| 16 | +{ |
| 17 | + "url": "https://example.com", |
| 18 | + "results": [ |
| 19 | + { |
| 20 | + "id": "module-id", |
| 21 | + "data": { |
| 22 | + "module_id": "module-id", |
| 23 | + "target": "https://example.com", |
| 24 | + "findings": [ |
| 25 | + { |
| 26 | + "url": "https://example.com/.git/HEAD", |
| 27 | + "severity": "high", |
| 28 | + "evidence": "ref: refs/heads/main", |
| 29 | + "extracted": { |
| 30 | + "branch": "main" |
| 31 | + } |
| 32 | + } |
| 33 | + ] |
| 34 | + } |
| 35 | + } |
| 36 | + ] |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +## fields |
| 41 | + |
| 42 | +### url |
| 43 | + |
| 44 | +the target url that was scanned. |
| 45 | + |
| 46 | +### results |
| 47 | + |
| 48 | +array of module results. |
| 49 | + |
| 50 | +### results[].id |
| 51 | + |
| 52 | +module identifier. |
| 53 | + |
| 54 | +### results[].data.findings |
| 55 | + |
| 56 | +array of security findings from the module. |
| 57 | + |
| 58 | +### findings[].url |
| 59 | + |
| 60 | +the specific url where the finding was detected. |
| 61 | + |
| 62 | +### findings[].severity |
| 63 | + |
| 64 | +severity level: `info`, `low`, `medium`, `high`, `critical` |
| 65 | + |
| 66 | +### findings[].evidence |
| 67 | + |
| 68 | +evidence that triggered the finding (matched content, etc). |
| 69 | + |
| 70 | +### findings[].extracted |
| 71 | + |
| 72 | +extracted data from the response (versions, keys, etc). |
| 73 | + |
| 74 | +## examples |
| 75 | + |
| 76 | +### save to file |
| 77 | + |
| 78 | +```bash |
| 79 | +./sif -u https://example.com -api -am > results.json |
| 80 | +``` |
| 81 | + |
| 82 | +### pipe to jq |
| 83 | + |
| 84 | +```bash |
| 85 | +./sif -u https://example.com -api -am | jq '.results[].data.findings[]' |
| 86 | +``` |
| 87 | + |
| 88 | +### filter high severity |
| 89 | + |
| 90 | +```bash |
| 91 | +./sif -u https://example.com -api -am | jq '.results[].data.findings[] | select(.severity == "high")' |
| 92 | +``` |
| 93 | + |
| 94 | +### extract urls |
| 95 | + |
| 96 | +```bash |
| 97 | +./sif -u https://example.com -api -am | jq -r '.results[].data.findings[].url' |
| 98 | +``` |
| 99 | + |
| 100 | +## ci/cd integration |
| 101 | + |
| 102 | +### github actions |
| 103 | + |
| 104 | +```yaml |
| 105 | +- name: run sif scan |
| 106 | + run: | |
| 107 | + ./sif -u ${{ env.TARGET_URL }} -api -am > sif-results.json |
| 108 | +
|
| 109 | +- name: check for high severity findings |
| 110 | + run: | |
| 111 | + HIGH_COUNT=$(jq '[.results[].data.findings[] | select(.severity == "high" or .severity == "critical")] | length' sif-results.json) |
| 112 | + if [ "$HIGH_COUNT" -gt 0 ]; then |
| 113 | + echo "Found $HIGH_COUNT high/critical severity findings" |
| 114 | + exit 1 |
| 115 | + fi |
| 116 | +``` |
| 117 | +
|
| 118 | +### gitlab ci |
| 119 | +
|
| 120 | +```yaml |
| 121 | +security_scan: |
| 122 | + script: |
| 123 | + - ./sif -u $TARGET_URL -api -am > sif-results.json |
| 124 | + - | |
| 125 | + if jq -e '.results[].data.findings[] | select(.severity == "critical")' sif-results.json > /dev/null; then |
| 126 | + echo "Critical findings detected" |
| 127 | + exit 1 |
| 128 | + fi |
| 129 | + artifacts: |
| 130 | + paths: |
| 131 | + - sif-results.json |
| 132 | +``` |
| 133 | +
|
| 134 | +## multiple targets |
| 135 | +
|
| 136 | +when scanning multiple urls, each target outputs a separate json object: |
| 137 | +
|
| 138 | +```bash |
| 139 | +./sif -u https://site1.com,https://site2.com -api |
| 140 | +``` |
| 141 | + |
| 142 | +outputs: |
| 143 | + |
| 144 | +```json |
| 145 | +{"url":"https://site1.com","results":[...]} |
| 146 | +{"url":"https://site2.com","results":[...]} |
| 147 | +``` |
| 148 | + |
| 149 | +use `jq -s` to combine into an array: |
| 150 | + |
| 151 | +```bash |
| 152 | +./sif -u https://site1.com,https://site2.com -api | jq -s '.' |
| 153 | +``` |
| 154 | + |
| 155 | +## notes |
| 156 | + |
| 157 | +- api mode suppresses banner and interactive output |
| 158 | +- all output goes to stdout |
| 159 | +- errors and warnings still go to stderr |
| 160 | +- combine with `-l` flag to also save detailed logs |
0 commit comments