docs/guide-ja/security-best-practices.md - added [ci skip]

docs/guide-ja/README.md

@@ -110,9 +110,9 @@ All Rights Reserved.
 
 * [認証](security-authentication.md)
 * [権限付与](security-authorization.md)
-* **翻訳中** [パスワードを扱う](security-passwords.md)
+* [パスワードを扱う](security-passwords.md)
 * **TBD** [Auth クライアント](security-auth-clients.md)
-* **翻訳中** [ベストプラクティス](security-best-practices.md)
+* [ベストプラクティス](security-best-practices.md)
 
 
 キャッシュ

docs/guide-ja/security-best-practices.md

+セキュリティのベストプラクティス
+================================
+
+下記において、一般的なセキュリティの指針を復習し、Yii を使ってアプリケーションを開発するときに脅威を回避する方法を説明します。
+
+基本的な指針
+------------
+
+どのようなアプリケーションが開発されているかに関わらず、セキュリティに関しては二つの大きな指針が存在します。
+
+1. 入力をフィルタする。
+2. 出力をエスケープする。
+
+
+### 入力をフィルタする
+
+入力をフィルタするとは、入力値は決して安全なものであると見なさず、取得した値が実際に許可さていれる値に含まれるか否かを常にチェックしなければならない、ということを意味します。
+つまり、並べ替えが三つのフィールド `title`、`created_at` および `status` によって実行され、フィールドの値がインプットによって提供されるものであることを知っている場合、取得した値を受信するその場でチェックする方が良い、ということです。
+基本的な PHP の形式では、次のようなコードになります。
+
+```php
+$sortBy = $_GET['sort'];
+if (!in_array($sortBy, ['title', 'created_at', 'status'])) {
+	throw new Exception('Invalid sort value.');
+}
+```
+
+Yii においては、たいていの場合、同様のチェックを行うために [フォームのバリデーション](input-validation.md) を使うことになるでしょう。
+
+
+### 出力をエスケープする
+
+データを使用するコンテキストに応じて、出力をエスケープしなければなりません。
+つまり、HTML のコンテキストでは、`<` や `>` などの特殊な文字をエスケープしなければなりません。
+JavaScript や SQL のコンテキストでは、対象となる文字は別のセットになります。
+全てを手動でエスケープするのは間違いを生じやすいことですから、Yii は異なるコンテキストに応じたエスケープを実行するためのさまざまなツールを提供しています。
+
+SQL インジェクションを回避する
+------------------------------
+
+SQL インジェクションは、次のように、エスケープされていない文字列を連結してクエリテキストを構築する場合に発生します。
+
+```php
+$username = $_GET['username'];
+$sql = "SELECT * FROM user WHERE username = '$username'";
+```
+
+正しいユーザ名を提供する代りに、攻撃者は `'; DROP TABLE user; --` のような文字列をあなたのアプリケーションに与えることが出来ます。
+結果として構築される SQL は次のようになります。
+
+```sql
+SELECT * FROM user WHERE username = ''; DROP TABLE user; --'
+```
+
+これは有効なクエリで、空のユーザ名を持つユーザを探してから、`user` テーブルを削除します。
+おそらく、ウェブサイトは破壊されて、データは失われることになります (定期的なバックアップは設定済みですよね、ね? )。
+
+Yii においては、ほとんどのデータベースクエリは、PDO のプリペアドステートメントを適切に使用する [アクティブレコード](db-active-record.md) を経由して実行されます。
+プリペアドステートメントの場合は、上で説明したようなクエリの改竄は不可能です。
+
+それでも、[生のクエリ](db-dao.md) や [クエリビルダ](db-query-builder.md) を必要とする場合はあります。
+その場合には、データを渡すための安全な方法を使わなければなりません。
+データをカラムの値として使う場合は、プリペアドステートメントを使うことが望まれます。
+
+```php
+// query builder
+$userIDs = (new Query())
+    ->select('id')
+    ->from('user')
+    ->where('status=:status', [':status' => $status])
+    ->all();
+
+// DAO
+$userIDs = $connection
+    ->createCommand('SELECT id FROM user where status=:status')
+    ->bindValues([':status' => $status])
+    ->queryColumn();
+```
+
+データがカラム名やテーブル名を指定するために使われる場合は、事前定義された一連の値だけを許可するのが最善の方法です。
+ 
+```php
+function actionList($orderBy = null)
+{
+    if (!in_array($orderBy, ['name', 'status'])) {
+        throw new BadRequestHttpException('名前とステータスだけを並べ替えに使うことが出来ます。')
+    }
+    
+    // ...
+}
+```
+
+それが不可能な場合は、テーブル名とカラム名をエスケープしなければなりません。
+Yii はそういうエスケープのための特別な文法を持っており、それを使うと、サポートされている全てのデータベースに対して同じ方法でエスケープすることが出来ます。
+
+```php
+$sql = "SELECT COUNT([[$column]]) FROM {{table}}";
+$rowCount = $connection->createCommand($sql)->queryScalar();
+```
+
+この文法の詳細は、[テーブルとカラムの名前を引用符で囲む](db-dao.md#quoting-table-and-column-names) で読むことが出来ます。
+
+
+XSS を回避する
+--------------
+
+XSS すなわちクロスサイトスクリプティングは、ブラウザに HTML を出力する際に、出力が適切にエスケープされていないと発生します。
+例えば、ユーザ名を入力できるフォームで `Alexander` の代りに `<script>alert('Hello!');</script>` と入力した場合、ユーザ名をエスケープせずに出力している全てのページでは、JavaScript `alert('Hello!');` が実行されて、ブラウザにアラートボックスがポップアップ表示されます。
+ウェブサイト次第では、そのようなスクリプトを使って、無害なアラートではなく、あなたの名前を使ってメッセージを送信したり、さらには銀行取引を実行したりすることが可能です。
+
+XSS の回避は、Yii においてはとても簡単です。一般に、二つのケースがあります。
+
+1. データを平文テキストとして出力したい。
+2. データを HTML として出力したい。
+
+平文テキストしか必要でない場合は、エスケープは次のようにとても簡単です。
+
+
+```php
+<?= \yii\helpers\Html::encode($username) ?>
+```
+
+HTML である場合は、HtmlPurifier から助けを得ることが出来ます。
+
+```php
+<?= \yii\helpers\HtmlPurifier::process($description) ?>
+```
+
+HtmlPurifier の処理は非常に重いので、キャッシュを追加することを検討してください。
+
+CSRF を回避する
+---------------
+
+TBD: what's CSRF, how it works, intro
+
+1. HTTP の規格に従うこと、すなわち、GET はアプリケーションの状態を変更すべきではない。
+2. Yii の CSRF 保護を有効にしておくこと。
+
+TBD: how CSRF protection works
+
+
+ファイルの曝露を回避する
+------------------------
+
+デフォルトでは、サーバのウェブルートは、`index.php` がある `web` ディレクトリを指すように意図されています。
+共有ホスティング環境の場合、それをすることが出来ずに、全てのコード、構成情報、ログをサーバのウェブルートの下に置かなくてはならないことがあり得ます。
+
+そういう場合には、`web` 以外の全てに対してアクセスを拒否することを忘れないでください。
+それも出来ない場合は、アプリケーションを別の場所でホストすることを検討してください。
+
+実運用環境ではデバッグ情報とデバッグツールを無効にする
+------------------------------------------------------
+
+デバッグモードでは、Yii は極めて多くのエラー情報を出力します。これは確かに開発には役立つものです。
+しかし、実際の所、これらの饒舌なエラー情報は、攻撃者にとっても、データベース構造、構成情報の値、コードの断片などを曝露してくれる重宝なものです。
+実運用のアプリケーションにおいては、決して `index.php` の `YII_DEBUG` を `true` にして走らせてはいけません。
+
+実運用環境では Gii を決して有効にしてはいけません。
+Gii を使うと、データベース構造とコードに関する情報を得ることが出来るだけでなく、コードを Gii によって生成したもので書き換えることすら出来てしまいます。
+
+デバッグツールバーは本当に必要でない限り実運用環境では使用を避けるべきです。
+これはアプリケーションと構成情報の全ての詳細を曝露することが出来ます。
+どうしても必要な場合は、あなたの IP だけに適切にアクセス制限されていることを再度チェックしてください。