# Semgrep으로 우리 팀 규칙 만들기: 파이썬 사용자 규칙 여섯 개와 규칙 시험

> Semgrep 규칙 여섯 개(SQL 문자열 조립, 인증서 검증 끄기, 약한 해시, 요청값이 셸로 흐르는 taint, shell=True, 팀 전용 함수 금지)를 직접 쓰고 semgrep --test로 시험한 뒤, 약한 코드와 고친 코드에 적용해 종료 코드 게이트를 만듭니다. bandit과 비교하고 규칙을 일부러 깨서 시험이 잡는지도 확인합니다.

- 주소: https://copyandrun.com/blog/semgrep-custom-rule-python/
- 분야: 시큐어코딩
- 발행일: 2026-10-30
- 태그: Semgrep, 사용자 규칙, taint, SAST, 파이썬

공개 규칙 모음만으로는 우리 팀의 약속을 검사하지 못합니다. 예를 들어 "`run_shell` 대신 `safe_run`을 쓴다" 같은 규칙은 어떤 공개 도구에도 없습니다. Semgrep은 코드 모양 그대로 규칙을 쓰는 도구라서 이런 팀 규칙을 몇 줄로 만들 수 있습니다. 이 글에서는 [CI에 Semgrep과 Bandit 보안 게이트 붙이기](/blog/ci-semgrep-bandit-gate/)에서 한 걸음 더 나아가, 공개 규칙을 가져다 쓰는 대신 규칙을 직접 쓰고, 규칙이 제대로 작동하는지 시험하고, 규칙을 일부러 망가뜨렸을 때 시험이 잡아내는지까지 확인합니다. Semgrep은 내 PC의 파일을 읽기만 하며 샘플 코드를 실행하지 않습니다.

## 준비물

| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11, Git Bash에서 실행) |
| Semgrep | 1.182.1 (`semgrep/semgrep` 이미지) |
| 비교용 | bandit 1.9.4 (`python:3.12-alpine`에서 `pip install`) |
| 파이썬 | 3.12 (JSON 요약 스크립트) |

Semgrep은 `--metrics off`로 통계 전송을 끄고 로컬 규칙 파일만 썼습니다. 레지스트리의 공개 규칙은 쓰지 않았습니다.

## 1. 규칙 여섯 개

<!-- files: company.yml -->

| 규칙 | 잡는 것 | 심각도 |
|---|---|---|
| `company-sql-string-built` | `db.execute(f"...")`, `"..." + x`, `"...".format()`으로 만든 SQL | ERROR |
| `company-tls-verify-false` | `requests.get(..., verify=False)` | ERROR |
| `company-weak-password-hash` | `hashlib.md5(...)`, `hashlib.sha1(...)` | WARNING |
| `company-os-command-taint` | `request.args.get`으로 받은 값이 `os.system`으로 전달됨(`shlex.quote`를 거치면 제외) | ERROR |
| `company-subprocess-shell-true` | `subprocess.*(..., shell=True)` | ERROR |
| `company-no-run-shell` | 팀 전용 규칙: `run_shell(...)` 호출 | ERROR |

규칙 파일은 아래 전체 코드의 `company.yml`입니다. 앞의 세 개는 `pattern` 한 줄이나 `pattern-either`로 충분했습니다. 네 번째는 `mode: taint`로 쓴 규칙인데, "값이 어디서 들어와 어디로 흘러가는가"를 따지므로 단순한 모양 맞추기와 다릅니다. 입구(`pattern-sources`), 출구(`pattern-sinks`), 정화 함수(`pattern-sanitizers`)를 각각 적습니다.

## 2. 규칙을 시험하기

규칙은 코드처럼 시험해야 합니다. `company.py`는 규칙 파일과 이름이 같은 시험 파일입니다. 걸려야 하는 줄 바로 위에 `# ruleid: 규칙이름`, 걸리면 안 되는 줄 바로 위에 `# ok: 규칙이름` 주석을 답니다.

```
## 1. 규칙 시험(semgrep --test)
6/6: ✓ All tests passed
```

시험 파일에는 규칙마다 걸리는 입력과 안 걸리는 입력을 한 쌍 이상 넣었고 6개 규칙이 모두 통과했습니다. 규칙이 어디서도 아무것도 못 잡는 상태(조용한 0건)를 가려내려면 이런 시험이 꼭 필요합니다.

## 3. 약한 코드와 고친 코드

`bad_app.py`와 `good_app.py`는 같은 함수 일곱 개를 각각 약하게 쓴 파일과 고쳐 쓴 파일입니다(SQL 조회 두 개, 비밀번호 해시, 외부 요청, ping, 백업, 정리). 같은 규칙 파일을 두 파일에 적용했습니다.

```
[bad_app.py]
  ERROR    1건  company-no-run-shell
  ERROR    1건  company-os-command-taint
  ERROR    2건  company-sql-string-built
  ERROR    1건  company-subprocess-shell-true
  ERROR    1건  company-tls-verify-false
  WARNING  1건  company-weak-password-hash
  합계 7건 (ERROR 6, WARNING 1)
  종료 코드 1
[good_app.py]
  합계 0건 (ERROR 0, WARNING 0)
  종료 코드 0
```

![semgrep_demo.sh 실행 결과에서 규칙 시험 6개 통과, 약한 코드는 ERROR 6건과 WARNING 1건으로 종료 코드 1, 고친 코드는 0건으로 종료 코드 0, bandit은 약한 코드 7건과 고친 코드 5건, 정리 항목을 삭제한 규칙은 시험 5/6으로 실패하는 것을 확인합니다.](https://copyandrun.com/img/semgrep-custom-rule-python/01-semgrep-시험-적용-교차확인.png)

- **고친 코드는 0건입니다.** `os.system("ping " + shlex.quote(host))`는 같은 `os.system`이지만 taint 규칙이 정화 함수를 인식해 걸리지 않았습니다.
- **SQL 규칙은 f-string과 문자열 더하기 두 건을 모두 잡았습니다.** `.format()` 쪽은 시험 파일에서만 확인했고 샘플 코드에는 넣지 않았습니다.
- **게이트는 ERROR만 셉니다.** `semgrep_summary.py`는 ERROR가 하나라도 있으면 종료 코드 1로 끝나고, WARNING(약한 해시)은 세기만 합니다. 이 기준은 내가 정한 것이며 Semgrep의 기본 동작이 아닙니다.

실제 화면은 아래와 같습니다. 규칙 이름, 메시지, 걸린 줄이 한 덩어리로 나옵니다.

![semgrep scan 화면에서 7개 결과 중 SQL 문자열 조립, 약한 해시, 인증서 검증 끄기, 셸 명령 taint, shell=True 규칙의 한국어 메시지와 걸린 줄이 보이는 것을 확인합니다.](https://copyandrun.com/img/semgrep-custom-rule-python/02-semgrep-탐지-화면.png)

## 4. 교차 확인: bandit과 비교

같은 두 파일을 bandit으로도 검사했습니다.

| 파일 | Semgrep 사용자 규칙 | bandit |
|---|---|---|
| `bad_app.py` | 7건 | 7건 |
| `good_app.py` | 0건 | 5건 |

- **약한 코드에서는 둘이 비슷하게 찾았습니다.** bandit은 `B608`(SQL 조립), `B324`(md5), `B501`(`verify=False`), `B605`(셸), `B602`(`shell=True`)와 `import subprocess` 경고(`B404`)를 냈습니다. 다만 7건이라는 숫자는 우연히 같을 뿐 종류가 다릅니다.
- **`run_shell`은 bandit이 모릅니다.** 팀 규칙은 사용자 규칙으로만 잡을 수 있습니다.
- **고친 코드에서 bandit은 5건을 냈습니다.** `import subprocess`(`B404`), `shlex.quote`를 거친 `os.system`(`B605`), 목록 인자 `subprocess.run`의 `B603`과 `B607`, `/tmp` 경로(`B108`)입니다. 모두 "확인해 보라"는 성격의 경고이고, 이 코드는 입력이 안전하게 처리되고 있어 조치가 필요한 결함은 아니라고 판단했습니다. 이 판단은 내가 코드를 읽고 한 것이며 bandit이 알려 준 것이 아닙니다. 그래서 같은 게이트에 bandit을 그대로 쓰면 고친 코드도 막힐 수 있습니다.

## 5. 규칙을 일부러 깨 보기

<!-- files: company.yml -->

taint 규칙에서 `pattern-sanitizers` 항목을 지운 사본으로 시험을 다시 돌렸습니다.

```
5/6: 1 unit tests did not pass:
	✖ company-os-command-taint
```

규칙 하나를 깨면 시험이 바로 알려 줍니다. 정화 함수가 빠지면 `shlex.quote`를 쓴 안전한 줄까지 걸려서 `# ok:` 시험이 실패한 것입니다. 이 시험이 없으면 규칙을 고치다가 오탐이 늘어도 눈치채지 못하고 CI 게이트만 계속 실패합니다.

## 6. 팀에 적용할 때

- 규칙 파일과 시험 파일을 같은 저장소에 두고, 규칙을 바꿀 때는 `semgrep --test`를 먼저 통과시킵니다.
- 새 결함이 발견되면 그 코드 한 줄을 `# ruleid:` 시험으로 먼저 추가하고 규칙을 고칩니다.
- 처음 켜는 규칙은 WARNING으로 시작해 오탐을 확인한 뒤 ERROR로 올립니다.

이 순서를 CI로 묶는 것은 이 글에서 하지 않았습니다. CI 설정은 앞의 Semgrep과 Bandit 게이트 글을 참고합니다.

## 전체 코드

전체를 한 번에 돌리는 스크립트입니다. 아래 파일과 같은 폴더에서 실행합니다.

```bash
# semgrep_demo.sh
#!/usr/bin/env bash
# 내가 만든 semgrep 규칙 여섯 개를 시험하고, 약한 코드와 고친 코드에 적용하고, bandit 과 비교하고, 규칙을 일부러 깨 본다.
# 준비: Docker, python, 같은 폴더에 company.yml, company.py, bad_app.py, good_app.py, semgrep_summary.py. 이미지는 처음 받을 때 몇 분 걸린다.
# 실행(Git Bash): bash semgrep_demo.sh   (약 3분)
export MSYS_NO_PATHCONV=1
HERE="$(pwd)"
OUT=../osk-fc-sg-out                       # 결과 폴더는 규칙 폴더 밖에 둔다
rm -rf "$OUT"; mkdir -p "$OUT"; ABS="$(cd "$OUT" && pwd)"
SG() { docker run --rm -v "$HERE:/src:ro" -v "$ABS:/out" -w /src semgrep/semgrep semgrep "$@"; }

echo "## 1. 규칙 시험(semgrep --test)"
SG --test . 2>&1 | grep -E '[0-9]+/[0-9]+'

echo "## 2. 약한 코드와 고친 코드에 적용"
for f in bad_app good_app; do
  SG scan --config company.yml --metrics off --quiet --json -o /out/$f.json $f.py >/dev/null 2>&1
  echo "[$f.py]"; python semgrep_summary.py "$OUT/$f.json"; echo "  종료 코드 $?"
done

echo "## 3. 교차 확인: bandit 이 같은 파일에서 찾는 것"
docker run --rm -v "$HERE:/code:ro" python:3.12-alpine sh -c 'pip install -q bandit >/dev/null 2>&1; bandit /code/bad_app.py /code/good_app.py -f custom --msg-template "{relpath}:{line} {test_id} {msg}" 2>/dev/null'   | grep '^code/' | sed 's#^code/##' | cut -c1-88 > "$OUT/bandit.txt"
for f in bad_app good_app; do echo "  $f.py: bandit $(grep -c "^$f.py" "$OUT/bandit.txt")건"; done
grep '^good_app' "$OUT/bandit.txt" | sed 's/^/    /'

echo "## 4. 규칙을 일부러 깨 보기: 정리(sanitizer) 항목 삭제"
mkdir -p "$OUT/broken"; cp company.py "$OUT/broken/"
python - "$OUT" <<'PY'
import sys
s = open("company.yml", encoding="utf-8").read()
cut = s.index("    pattern-sanitizers:")
end = s.index("  - id: company-subprocess-shell-true")
open(sys.argv[1] + "/broken/company.yml", "w", encoding="utf-8", newline="\n").write(s[:cut] + "\n" + s[end:])
PY
docker run --rm -v "$ABS/broken:/b:ro" -w /b semgrep/semgrep semgrep --test . 2>&1 | grep -E '✓|✘|[0-9]+/[0-9]+|company-os' | head -6
echo "## 끝 (결과 폴더: $OUT)"
```

규칙 파일입니다. 규칙 여섯 개가 들어 있습니다.

`company.yml`

```yaml
rules:
  - id: company-sql-string-built
    languages: [python]
    severity: ERROR
    message: SQL 문자열을 f-string, 문자열 더하기, format 으로 만들지 말고 ? 자리표시자로 값을 넘깁니다.
    pattern-either:
      - pattern: $DB.execute(f"...")
      - pattern: $DB.execute("..." + $X)
      - pattern: $DB.execute("...".format(...))

  - id: company-tls-verify-false
    languages: [python]
    severity: ERROR
    message: 인증서 검증을 끄지 않습니다. verify=False 를 제거합니다.
    pattern: requests.$FUNC(..., verify=False, ...)

  - id: company-weak-password-hash
    languages: [python]
    severity: WARNING
    message: 비밀번호에 md5 나 sha1 을 쓰지 않습니다. scrypt, bcrypt, argon2 를 씁니다.
    pattern-either:
      - pattern: hashlib.md5(...)
      - pattern: hashlib.sha1(...)

  - id: company-os-command-taint
    languages: [python]
    severity: ERROR
    mode: taint
    message: 요청에서 받은 값이 셸 명령으로 흘러갑니다. 목록 인자로 실행하거나 shlex.quote 를 거칩니다.
    pattern-sources:
      - pattern: request.args.get(...)
    pattern-sinks:
      - pattern: os.system(...)
    pattern-sanitizers:
      - pattern: shlex.quote(...)

  - id: company-subprocess-shell-true
    languages: [python]
    severity: ERROR
    message: shell=True 로 실행하지 않습니다. 명령을 목록으로 나눠 넘깁니다.
    pattern: subprocess.$F(..., shell=True, ...)

  - id: company-no-run-shell
    languages: [python]
    severity: ERROR
    message: 우리 팀은 run_shell 대신 safe_run 을 씁니다.
    pattern: run_shell(...)
```

규칙 시험 파일입니다. 이름이 규칙 파일과 같아야 합니다.

```python
# company.py
# 규칙 시험 파일: semgrep --test 가 규칙 파일과 이름이 같은 이 파일을 읽는다.
# 주석 표시가 붙은 바로 다음 줄은 걸려야 하는 줄, ok 표시가 붙은 바로 다음 줄은 걸리면 안 되는 줄이다.
import hashlib
import os
import shlex
import subprocess

import requests
from flask import request

from helpers import run_shell


def sql(db, name, n):
    # ruleid: company-sql-string-built
    db.execute(f"SELECT * FROM t WHERE a = '{name}'")
    # ruleid: company-sql-string-built
    db.execute("SELECT * FROM t WHERE a = " + n)
    # ruleid: company-sql-string-built
    db.execute("SELECT * FROM t WHERE a = {}".format(n))
    # ok: company-sql-string-built
    db.execute("SELECT * FROM t WHERE a = ?", (name,))


def tls(url):
    # ruleid: company-tls-verify-false
    requests.get(url, verify=False)
    # ok: company-tls-verify-false
    requests.get(url, timeout=5)


def hashing(p):
    # ruleid: company-weak-password-hash
    hashlib.md5(p)
    # ruleid: company-weak-password-hash
    hashlib.sha1(p)
    # ok: company-weak-password-hash
    hashlib.sha256(p)


def taint():
    host = request.args.get("host")
    # ruleid: company-os-command-taint
    os.system("ping " + host)
    # ok: company-os-command-taint
    os.system("ping " + shlex.quote(host))
    # ok: company-os-command-taint
    os.system("ping 127.0.0.1")


def shell(path):
    # ruleid: company-subprocess-shell-true
    subprocess.run("ls " + path, shell=True)
    # ok: company-subprocess-shell-true
    subprocess.run(["ls", path])


def internal(cmd):
    # ruleid: company-no-run-shell
    run_shell(cmd)
    # ok: company-no-run-shell
    safe_run(cmd)
```

일부러 약하게 쓴 샘플입니다. 실행하지 않고 읽기만 합니다.

```python
# bad_app.py
import hashlib
import os
import subprocess

import requests
from flask import request

from helpers import run_shell


def find_user(db, name):
    return db.execute(f"SELECT * FROM users WHERE name = '{name}'").fetchall()


def find_order(db, order_id):
    return db.execute("SELECT * FROM orders WHERE id = " + order_id).fetchall()


def hash_password(password):
    return hashlib.md5(password.encode()).hexdigest()


def fetch_report(url):
    return requests.get(url, verify=False, timeout=5).text


def ping():
    host = request.args.get("host")
    return os.system("ping -c 1 " + host)


def backup(path):
    return subprocess.run(f"tar czf /tmp/backup.tgz {path}", shell=True)


def cleanup(cmd):
    return run_shell(cmd)
```

고친 샘플입니다.

```python
# good_app.py
import hashlib
import os
import shlex
import subprocess

import requests
from flask import request

from helpers import safe_run


def find_user(db, name):
    return db.execute("SELECT * FROM users WHERE name = ?", (name,)).fetchall()


def find_order(db, order_id):
    return db.execute("SELECT * FROM orders WHERE id = ?", (int(order_id),)).fetchall()


def hash_password(password, salt):
    return hashlib.scrypt(password.encode(), salt=salt, n=2**14, r=8, p=1).hex()


def fetch_report(url):
    return requests.get(url, timeout=5).text


def ping():
    host = request.args.get("host")
    return os.system("ping -c 1 " + shlex.quote(host))


def backup(path):
    return subprocess.run(["tar", "czf", "/tmp/backup.tgz", path], check=True)


def cleanup(cmd):
    return safe_run(cmd)
```

JSON 결과를 요약하고 ERROR 가 있으면 종료 코드 1로 끝내는 스크립트입니다.

```python
# semgrep_summary.py
#!/usr/bin/env python3
"""semgrep 의 JSON 결과를 규칙별로 세고, ERROR 가 하나라도 있으면 종료 코드 1로 끝낸다.
사용: python semgrep_summary.py out.json   (WARNING 은 세기만 하고 게이트에는 쓰지 않는다)"""
import collections
import json
import sys

sys.stdout.reconfigure(encoding="utf-8")

data = json.load(open(sys.argv[1], encoding="utf-8"))
count = collections.Counter()
levels = collections.Counter()
for r in data["results"]:
    rule = r["check_id"].split(".")[-1]
    level = r["extra"]["severity"]
    count[(level, rule)] += 1
    levels[level] += 1
for (level, rule), n in sorted(count.items()):
    print(f"  {level:<8} {n}건  {rule}")
print(f"  합계 {sum(levels.values())}건 (ERROR {levels['ERROR']}, WARNING {levels['WARNING']})")
sys.exit(1 if levels["ERROR"] else 0)
```

## 자주 막히는 곳

| 증상 | 원인 | 해결 |
|---|---|---|
| `semgrep --test --config company.yml 폴더`가 `IndexError: tuple index out of range`로 죽음 | 이 버전에서 `--config`와 대상 폴더를 같이 주면 시험 파일 짝짓기에서 실패 | `semgrep --test .`처럼 폴더만 지정 |
| `Found rule id mismatch ... 'ruleid' annotation with no YAML rule` | 시험 파일의 설명 주석에 `ruleid:` 라는 글자가 있어 규칙 표시로 읽힘 | 설명 주석에서 그 단어를 빼고 표시 주석만 둠 |
| `--test`가 시험 파일을 못 찾음 | 시험 파일 이름이 규칙 파일과 다름 | `company.yml`과 `company.py`처럼 확장자만 다르게 |
| 한글 메시지가 깨져 보임 | 터미널 인코딩 | 요약 스크립트에서 `sys.stdout.reconfigure(encoding="utf-8")` |
| 결과 폴더의 JSON까지 검사됨 | 결과를 검사 대상 폴더 안에 저장 | 결과 폴더를 `../osk-fc-sg-out`처럼 바깥에 둠 |

## 확인 범위

- **해 본 것:** 2026-10-30, Windows 11 · Docker 29.5.3 · Semgrep 1.182.1에서 사용자 규칙 6개의 시험(6/6 통과), 약한 코드 7건과 고친 코드 0건의 적용, ERROR 기준 종료 코드, bandit 1.9.4와의 비교, 정화 항목을 지운 규칙의 시험 실패(5/6)를 실행했습니다. 전체 스크립트를 세 번 실행해 결과가 같았고, 컨테이너는 `--rm`으로 실행해 남지 않았습니다.
- **해 보지 않은 것:** 공개 규칙 레지스트리와의 조합, 실제 Flask 앱 전체 검사, 자동 수정(`fix:`), 규칙의 성능과 대용량 저장소, `.semgrepignore`, CI 연동, Linux와 macOS.
- **읽을 때 주의:** 규칙은 이 샘플 파일에 맞춘 예시입니다. 실제 코드에서는 `db.execute` 이름이나 `request` 객체가 다를 수 있어 규칙을 맞춰 써야 합니다. bandit의 5건을 조치 불필요로 본 판단은 이 샘플에 한정됩니다.
