CASTOR - AI Pentest Assistant

プロジェクト概要

• 本ツールはサイバーセキュリティ学習支援を目的とした、安全性と適用性を重視したAI支援アプリケーションです。

• フルスタック開発によりAPIキーおよびセキュリティに関する機微情報をユーザーの責任で管理出来ます。

• PoCとしての位置付けであり、AIモデルの変更、ツール呼び出し機能実装の余地を残しています。

• このアプリについての記事 (https://zenn.dev/forwardone/articles/94011d7c329361)

• CVE-2025-55182 対応済

主要な設計原則:

• 限定された利用環境と対象ユーザー: VM環境上での動作と対象マシンへのVPN接続を前提とし、基礎的なIT知識を持つユーザーを対象としています。
• 最小限の外部依存: APIキーやチャット履歴などの機密情報は外部に送信せず、ローカル環境で完結します。
• 運用負荷と環境干渉の最小化: Dockerやクラウドデプロイは使用せず、VM上でのメモリ消費やネットワークログへの干渉を避ける設計です。
• AI応答制御によるガバナンス設計: 内部プロンプト制御により、リスクを低減・防止します。モデルやフェーズごとの設定を統一し、結果のばらつきを抑制します。
• 拡張性・再現性の確保: スキャン結果や解析結果を標準化されたJSON形式で保持し、後続処理やレポート生成に活用可能です。CLIとの統合も視野に入れています。

動作イメージ

利用上の注意

• 利用の際は必ず自己責任で学習目的かつ提供された環境内に限定してください。
• 一般のネットワーク環境に対して無許可でハッキング及びそれらに該当する侵害行為を行うのは犯罪です。

機能一覧

• AIとのチャットを通じたサイバーセキュリティ学習支援
• セキュリティ学習向けに調整されたシステム指示による指向性のある出力
• 目的フェーズ間のコンテキスト引継ぎの補助となるjsonサマリー出力
• チャット履歴の管理
• Markdownおよびコードブロックの整形表示

---

技術スタック

バックエンド

• 言語: Python 3.10+
• フレームワーク: FastAPI
• AI SDK: Google Generative AI SDK (google-genai)
• その他: Pydantic, python-dotenv

フロントエンド

• フレームワーク: React
• ビルドツール: Vite
• 言語: TypeScript
• ルーティング: React Router
• UIライブラリ: shadcn/ui
• スタイリング: Tailwind CSS
• Markdownレンダリング: react-markdown, remark-gfm, rehype-highlight

---

セットアップ手順

前提条件

• Python 3.10+
• Node.js (LTS推奨)
• npm または yarn

1. リポジトリのクローン

git clone https://github.com/your-repo/castor.git
cd castor

2. 環境変数の設定

• プロジェクトルート (castor/) に .env ファイルを作成し、Google AI Studioから取得したAPIキーを設定します。
• APIを無料枠で使用する場合、2.5-flashモデルの仕様を推奨します。

GEMINI_API_KEY="YOUR_API_KEY_HERE"

3. セットアップ

仮想環境の作成とアクティベート

# プロジェクトルートで実行
python -m venv backend/venv
# Windows
backend\venv\Scripts\activate
# macOS/Linux
source backend/venv/bin/activate

依存関係のインストール

# 仮想環境がアクティブな状態で実行
pip install -r backend/requirements.txt

cd frontend
npm install

4.起動

プロジェクトルートに配置されている start.bat を実行することで、バックエンドとフロントエンドを同時に起動できます。
このスクリプトは、新しいウィンドウでバックエンドとフロントエンドをそれぞれ起動します。
個別に起動する場合は以下の方法で可能です。

バックエンドの起動

cd backend
uvicorn app.main:app --reload

サーバーは http://127.0.0.1:8000 で起動します。

フロントエンドの起動

cd frontend
npm run dev

アプリケーションは http://localhost:5173 でアクセス可能になります。

---

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

---

現在の課題

• PoC的なポートフォリオのため細かい更新が多く、バージョニング管理の必要性は検討中。
• READMEへのアーキテクチャ図の追加。
• 業務的なチケット化・スコープ管理を意識したが、個人開発では難しい部分が多かった。
  →Issueを立てセルフレビューをするようにした。
• テストコードでの実施が課題。自動化も含め勉強の必要性を感じている。
  →Pytest,Vitest,Github Actions導入

---

開発履歴

(クリックしてください)

2025-11-06:

• プロジェクトの初期セットアップとディレクトリ構成の整理。
• バックエンド（FastAPIエンドポイント、GeminiAPI呼び出し、型定義、CRUDロジック）を実装。

2025-11-07:

• React Routerを導入しSPAの基礎を構築。
• UI基盤としてshadcn/uiとTailwind CSSを導入し、レイアウトに必要なコンポーネント群を追加。

2025-11-12:

• フロントエンドのアーキテクチャを大幅に刷新。
• 将来を見据え、ルーティングとディレクトリ構成を再設計。カスタムフックの作成。

2025-11-15:

• チャット開始フローを全面的にリファクタリングし、UI/UXを改善。

2025-11-16:

• Google GenAI SDK準拠で設計したフェーズ別プロンプトを実装。
• フロントエンドにMarkdownレンダリングを追加。
• READMEを更新し、プロジェクトの目的、設計原則、セットアップ手順、技術スタックを明確化。
• READMEに動作イメージのスクリーンショットを追加。

2025-11-20:

• 履歴削除機能とUI改善、ダークテーマ/トグルを追加。
• 軽微なバグ修正を実施。
• サイドバーをリファクタリングしコンポーネント分割。

2025-11-23:

• プロジェクトルートにimagesディレクトリを作成し、スクリーンショットを移動。
• README.md内の画像パスをローカルのimagesディレクトリを参照するように更新。
• ウェルカム画面にフェーズ説明を追加。

2025-11-26:

• ライセンスの追加。
• サイドバーのコンポーネントの最適化、メモパッド機能を追加。

2025-11-27:

• テストコードの導入
• GitHub ActionsのCIワークフローを追加