紀錄工作經驗、相關知識,解決技術相關問題。

MySQL, 網站相關

ORM SQL Injection 安全迷思:Prisma 與 TypeORM 如何避免注入漏洞

ORM SQL Injection 安全迷思:Prisma 與 TypeORM 如何避免注入漏洞 特色圖片

ORM SQL Injection 的風險通常不出在 ORM 本身,而是出在開發者繞過它:改用原生查詢並拼接字串、把客戶端傳來的物件直接放進查詢條件,或讓前端決定 ORDER BY 欄位。Prisma、TypeORM、Sequelize 都提供參數綁定的用法,用錯方式就等於沒有防護。

把專案部署至生產環境之前(相關環境差異可參考 Prod 縮寫是什麼? 與 UAT 的差別),開發團隊必須徹底釐清 ORM 在底層處理 SQL 組合時的行為邊界。

想了解基礎 SQL 注入防禦原理,可前往 Prepared Statements 參數化查詢如何防範 SQL Injection 與防禦實務 觀看。以下直接提供現代 ORM 框架在安全查詢與原生語法防護上的核心對照與排錯指引。


一、 核心語法速查與規格對照

在高頻查詢或複雜動態條件的業務場景中,開發者常需在 ORM 抽象層與原生 SQL 之間取捨。以下為 Prisma 與 TypeORM 在安全參數綁定與高風險寫法上的規格對照表:

ORM 框架ORM 一般查詢寫法高風險寫法(易致 SQL Injection)底層驅動防禦機制
Prismaprisma.user.findMany({ where: { email } })prisma.$queryRawUnsafe(`SELECT * FROM users WHERE email = '`email'`)“queryRaw搭配樣板字串或Prisma.sql`,變數會以預備語句的參數傳送
TypeORMrepository.find({ where: { email } })dataSource.query(`SELECT * FROM users WHERE email = '${email}'`)query() 的第二個參數傳入陣列,SQL 內依資料庫使用 ?、$1 等佔位符
SequelizeModel.findAll({ where: { email } })sequelize.query(`SELECT * FROM users WHERE email = '${email}'`)原生查詢可用 bind parameters(值在 SQL 文字之外傳送)或 replacements(由 Sequelize 跳脫後插入 SQL 文字)

補充說明:Sequelize 官方文件指出,replacements 是由 Sequelize 跳脫後插入查詢再送往資料庫,bind parameters 則在 SQL 文字之外傳送。OWASP 建議以參數綁定為主,不要以手動跳脫取代;因此原生查詢優先選 bind parameters。

終端機顯示 Sequelize 拼接字串、replacements 與 bind 輸入惡意字串後的結果與記錄的 SQL
圖:Windows 11、Node.js v22.20.0,Sequelize 6.37.8 搭配 SQLite 的輸出;最後兩行為 replacements 與 bind 實際記錄的 SQL 文字

當必須執行複雜的原生查詢時,正確的 Prisma 範本寫法應使用帶有標籤的樣板字串:

import { PrismaClient, Prisma } from '@prisma/client';

const prisma = new PrismaClient();

// 安全的原生查詢範例(使用 Prisma.sql 樣板字串)
async function findUserByEmail(email: string) {
  const result = await prisma.$queryRaw(
    Prisma.sql`SELECT id, email, role FROM users WHERE email = ${email}`
  );
  return result;
}
終端機顯示 Prisma 的 `queryRaw、`queryRawUnsafe 與 Prisma.raw 輸入惡意字串後的查詢結果
圖:Windows 11、Node.js v22.20.0,Prisma 7.10.1 搭配 SQLite(better-sqlite3 驅動)的輸出;Prisma.sql 與位置參數查無資料,拼接字串與 Prisma.raw 回傳全部列

補充說明:上方範例中的 new PrismaClient() 省略了連線設定。Prisma 7 的 PrismaClient 需要傳入 driver adapter(例如 SQLite 用 @prisma/adapter-better-sqlite3),並以 prisma.config.ts 設定資料庫連線;$queryRaw 與 Prisma.sql 的用法不受影響。


二、 關鍵機制與跨情境細部拆解

1. Prisma 與 TypeORM 原生查詢的危險紅區

多數開發者誤以為只要使用 ORM 就絕對不會遭遇 SQL Injection。事實上,當使用 Prisma 的 $queryRawUnsafe 或 TypeORM 的 query() 直接串接字串變數時,變數內容就成為 SQL 文字的一部分,資料庫無法分辨哪些是指令、哪些是資料。

Prisma 官方文件指出,$queryRaw 只接受樣板字串或 Prisma.sql,不接受純字串;$queryRawUnsafe 則被官方標示為可能讓程式碼暴露於 SQL Injection 的方法。另外,把不可信輸入包進 Prisma.raw() 也會讓查詢變得可注入。

托盤中放著一封密封信封,幾張紙條放在信封之外,比喻資料與指令分開處理
圖:字串拼接與參數綁定的差別

高風險寫法範例:

// TypeORM 錯誤示範:直接以字串模板拼接參數
const users = await dataSource.query(
  `SELECT * FROM users WHERE name = '${userInputName}'`
);

解法:
使用參數化陣列傳遞,讓資料庫驅動程式將變數視為純資料而非執行指令:

// TypeORM 解法:使用參數佔位符(MySQL 為 ?,PostgreSQL 為 $1)
const users = await dataSource.query(
  `SELECT * FROM users WHERE name = ?`,
  [userInputName]
);
終端機顯示 TypeORM dataSource.query 拼接字串與佔位符輸入惡意字串後的結果
圖:Windows 11、Node.js v22.20.0,TypeORM 1.1.2 搭配 SQLite 的輸出;SQLite 的佔位符同為 ?

補充說明:TypeORM 官方文件列出各資料庫的佔位符寫法不同:MySQL 系列為 ?,PostgreSQL 系列為 $1、$2,MSSQL 為 @0、@1,Oracle 為 :1、:2。

2. 物件過濾條件遭惡意物件注入排查

當客戶端以 JSON 形式傳遞查詢條件(例如透過 req.query 或 req.body),若未經過 DTO(Data Transfer Object)驗證或型別轉換,攻擊者可能送出物件而不是預期的字串,讓查詢條件被改寫。

以 Prisma 為例,where 本身就支援 not、gt、contains 等運算子物件。若把客戶端傳來的值原封不動放進 where,攻擊者送出 { "not": "" } 就能把「email 等於某值」改成「email 不等於空字串」,條件變成幾乎全部符合。

問題程式碼範例:

// email 直接取自 req.body;攻擊者送出 { "email": { "not": "" } } 時,
// 這裡的條件就變成「email 不等於空字串」
const user = await prisma.user.findFirst({
  where: { email: req.body.email },
});
終端機顯示 Prisma where 傳入運算子物件與 TypeORM find 傳入物件的結果
圖:Windows 11、Node.js v22.20.0,Prisma 7.10.1 與 TypeORM 1.1.2 搭配 SQLite 的輸出;Prisma 回傳全部列,TypeORM 傳入純物件則拋出錯誤

TypeORM 的 FindOperator(例如 Not()、MoreThan())是由程式碼呼叫函式產生的,不是 JSON 能直接帶入的;MongoDB 風格的 $ne 也不是 TypeORM 關聯式查詢的語法。

TypeORM 的實際風險案例是 CVE-2025-60542:依 GitHub 安全公告,TypeORM 0.3.26 之前的版本,若把巢狀物件傳給 repository.save 或 repository.update,MySQL 驅動預設的 stringifyObjects: false 會讓巢狀物件被展開,攻擊者可以多塞入開發者不打算更新的欄位。

解法:
在 API 接收端先驗證型別,再把值交給 ORM。以 NestJS 為例,ValidationPipe 搭配 DTO,@IsString() 會讓物件型態的 email 驗證失敗;啟用 whitelist: true 可移除 DTO 中沒有裝飾器的屬性,再加 forbidNonWhitelisted: true 則直接拒絕多餘屬性。同時把 TypeORM 升級到 0.3.26 以上。

import { IsEmail, IsString } from 'class-validator';

export class FindUserDto {
  @IsString()
  @IsEmail()
  email: string;
}

// main.ts:全域啟用驗證,移除並拒絕 DTO 以外的屬性
app.useGlobalPipes(
  new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }),
);
終端機顯示 class-validator 對物件型態 email 與多餘屬性的驗證結果
圖:Windows 11、Node.js v22.20.0,class-validator 0.15.1 與 class-transformer 0.5.1 的輸出;驗證選項與上方 ValidationPipe 設定相同

3. 動態欄位排序(ORDER BY)的白名單校驗

參數化查詢(Parameterized Queries)無法直接作用於 SQL 語法中的結構性欄位(如 ORDER BY 欄位名稱或 ASC/DESC 排序方向)。當開發者允許前端傳入排序欄位時,必須在應用程式層實作嚴格的白名單對照,否則將導致 SQL Injection 或盲注攻擊。

木板上掛著三把鑰匙,旁邊有一個上鎖的金屬盒,比喻只允許白名單內的排序欄位
圖:只放行白名單內的排序欄位

解法:

const ALLOWED_SORT_COLUMNS = ['createdAt', 'email', 'name'];
const ALLOWED_DIRECTIONS = ['ASC', 'DESC'];

function getSafeOrder(sortBy: string, direction: string) {
  const column = ALLOWED_SORT_COLUMNS.includes(sortBy) ? sortBy : 'createdAt';
  const dir = ALLOWED_DIRECTIONS.includes(direction.toUpperCase()) ? direction.toUpperCase() : 'ASC';
  return { column, dir };
}

三、 常見問題與排錯(Q&A)

1. TypeORM 中使用 query 執行原生 SQL 時,如何正確綁定參數以防止 SQL Injection?

  • 問題原因:直接使用字串拼接或樣板字串(Template Literals)將變數嵌入 SQL 語句中,導致資料庫無法區分指令與資料。
  • 解法:在 dataSource.query() 的第二個參數傳入陣列,SQL 語句中依資料庫使用佔位符:MySQL 為 ?,PostgreSQL 為 $1、$2。

2. Prisma 的 Prisma.sql 樣板字串是否能完全免疫 SQL Injection?

  • 問題原因:開發者常混淆 $queryRaw 與 $queryRawUnsafe 的運作機制。
  • 解法:$queryRaw 搭配樣板字串或 Prisma.sql 時,Prisma 官方文件說明變數會以預備語句的參數傳送,值不會成為 SQL 文字的一部分。
  • 例外:把不可信輸入交給 Prisma.raw(),或對 $queryRawUnsafe 拼接字串,仍會產生可注入的查詢。因此「免疫」只限於變數確實由樣板字串的插值傳入的情況。

3. 什麼是物件注入(Object Injection)攻擊?如何透過 ORM 查詢條件中的巢狀物件繞過驗證?

  • 問題原因:請求內容夾帶未經型別驗證的物件,查詢條件中本該是字串的值被換成物件,例如 Prisma 的 { not: '' },使條件被改寫。
  • 解法:在 API 接收端用 DTO 驗證每個欄位的型別,拒絕或移除 DTO 未定義的屬性,詳見上方第二節。

4. 當 TypeORM 必須動態拼接排序欄位(ORDER BY)時,如何實作白名單校驗?

  • 問題原因:SQL 的欄位名稱與排序方向無法使用標準的參數化查詢綁定。
  • 解法:建立允許使用的欄位名稱常數陣列,並在組合 SQL 前進行嚴格的比對與過濾,對照方式見上方第三節。

5. Prisma 的 queryRaw 與 queryRawUnsafe 在底層實作上有何安全差異?

  • 問題原因:二者接受的參數型別不同,處理字串插值的方式也有所區別。
  • 解法:$queryRaw 只接受樣板字串或 Prisma.sql,變數會以預備語句的參數傳送;$queryRawUnsafe 接受純字串,若直接拼接變數就會產生漏洞。
  • 補充:$queryRawUnsafe 也可以用位置參數傳值,例如 prisma.$queryRawUnsafe("SELECT * FROM users WHERE email = $1", email)(PostgreSQL 寫法,MySQL 為 ?),但官方仍標示這類方法有 SQL Injection 風險,除非必須組出動態 SQL,否則優先用 $queryRaw。

6. 如何在 CI/CD 流程中檢測 ORM 的高風險 SQL 查詢?

  • 問題原因:人工 Code Review 容易遺漏隱蔽的動態 SQL 拼接或不安全的原生查詢。
  • 解法:在 CI/CD 管道導入靜態應用程式安全測試(SAST)工具,例如 Semgrep。Semgrep 官方文件說明其規則以程式碼樣式比對與資料流分析為基礎,可自訂規則掃描專案中的 $queryRawUnsafe 與 dataSource.query 呼叫,找出把變數拼進字串的寫法。

參考資料與延伸閱讀

發佈留言