@onlytems/security-scanner 🛡️

OnlyItems 백엔드 소스코드를 위한 엔터프라이즈급 정적 보안 분석 도구(SAST) 입니다. 코드 내에 숨겨진 보안 취약점과 엔터프라이즈 가이드라인 위반 사항을 배포 전에 선제적으로 탐지합니다.

🌟 주요 특징 (Key Features)

• 정적 분석(SAST): 코드를 실행하지 않고 패턴 매칭을 통해 잠재적 결함을 신속하게 탐지합니다.
• 5대 핵심 영역 점검: 인증, 데이터 보호, 입력값 검증, 인프라 설정, 보안 관제 영역의 룰셋 내장.
• 가이드라인 연계: 단순 탐지를 넘어, 위반 사항 발생 시 즉시 적용 가능한 Best Practice를 함께 제공합니다.
• 독립형 CLI: 어떤 Node.js 프로젝트에서도 의존성 없이 즉시 실행 가능합니다.

🛠️ 설치 방법 (Installation)

1. 개발 의존성으로 설치 (권장)

프로젝트의 보안 품질 관리를 위해 개발 도구로 추가합니다.

npm install @onlytems/security-scanner --save-dev

2. 전역 설치

어떤 폴더에서든 점검 도구로 사용하려면 전역으로 설치하십시오.

npm install -g @onlytems/security-scanner

3. 설치 없이 즉시 실행 (npx)

설치 과정 없이 일회성 스캔을 수행할 때 유용합니다.

npx @onlytems/security-scanner

🚀 사용 방법 (Usage)

CLI 명령어

패키지 설치 후, 터미널(프로젝트 루트)에서 다음 명령어를 실행합니다.

# 기본 스캔 실행
onlytems-scan

package.json 활용

package.json의 스크립트에 등록하여 팀원들과 공유하십시오.

{
  "scripts": {
    "security:check": "onlytems-scan"
  }
}

🔍 점검 규칙 및 탐지 로직 (Detection Rules)

이 도구는 다음 5가지 카테고리의 엔터프라이즈 보안 가이드라인을 준수하는지 확인합니다.

| 분류 | 탐지 대상 (Logic) | 해결 권고 (Best Practice) | | :--- | :--- | :--- | | 인증 & 인가 | 과도하게 긴 JWT 만료 시간 설정 | Access 1h / Refresh 30d 이내 분리 설정 | | 데이터 보호 | MD5/SHA-1 해시 사용, 하드코딩된 API Key/비밀번호 | Bcrypt/Argon2 사용 및 환경변수 관리 | | 입력값 검증 | 문자열 결합 방식의 SQL 쿼리, 시스템 커맨드 직접 실행 | Parameterized Query 및 입력값 필터링 | | 인프라 설정 | 운영 환경에 노출될 위험이 있는 테스트/디버그 엔드포인트 | 배포 본 소스 제외 또는 NODE_ENV 가드 적용 | | 보안 관제 | 로그(console.log) 출력문에 토큰, 비밀번호 등 평문 포함 | 로깅 전용 레이어 마스킹(Masking) 처리 |

📊 결과 보고서 해석 (Interpreting Results)

스캔 결과 위반 사항이 발견되면 아래와 같이 출력됩니다.

[대분류: 데이터 보호]
  ● 하드코딩된 민감 정보 (DATA-2-HARDCODED-SECRET)
    - 위치: controllers/authController.js:42
    - 증거: const API_KEY = 'YOUR_SECRET_KEY_HERE'...
    - 권고: KMS 연동 또는 환경변수(.env) 관리 필수

1. 위치: 취약점이 발견된 파일명과 정확한 라인 번호입니다.
2. 증거: 스캐너가 위반으로 판단한 코드의 일부분입니다.
3. 권고: 해당 위반 사항을 안전하게 수정하기 위한 구체적인 보안 가이드라인입니다.

⚙️ 상세 설정 및 오탐 관리

육안 심사 병행 (CHECKLIST.md)

정적 분석만으로 확인할 수 없는 논리적 권한 검증(IDOR 등)은 동봉된 security-scanner/CHECKLIST.md 문서를 기반으로 육안 점검을 병행해야 합니다.

탐지 제외 (Exclude)

• .env, node_modules, .git, package.json, swagger.json 등 설정 및 라이브러리 폴더는 기본적으로 스캔 대상에서 제외됩니다.
• 테스트 코드(*.spec.js) 등 의도적인 더미 데이터 탐지 시, 리포트 확인 후 예외 처리하십시오.

🤖 CI/CD 통합 예시

GitHub Actions 등 CI 파이프라인에 통합하여 보안 취약점 배포를 자동 차단하십시오.

# .github/workflows/security-scan.yml
jobs:
  security-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install
      - name: Security Scan
        run: npx @onlytems/security-scanner

Created by Gemini CLI Security Module