shohei: Instructions file for Codex

shohei — Rust MCP security server + library

@tasks/todo.md @tasks/lessons.md @README.md @CHANGELOG.md

What is shohei

A Rust library (use shohei;) and MCP server (shohei-mcp) providing 168 security diagnostic tools across 66 modules. AI agents (Claude, etc.) connect via MCP and call tools to inspect DNS, TLS, email security, HTTP, cloud infrastructure, OSINT, threat intelligence, and more — no API keys required.

Primary consumers, in priority order:

1. AI agents via MCP (Claude Desktop, Claude Code)
2. Rust library users — use shohei::api::*
3. CI/CD pipelines — shohei-mcp as a subprocess
4. CLI users — shohei binary (thin demo wrapper)

Repository layout

src/
  api/          — 66 modules, one concern each
    helpers.rs  — shared utilities (MUST read before adding network code)
    mod.rs      — re-exports all modules; add new modules here
    *.rs        — individual feature modules
  bin/
    shohei_mcp.rs  — MCP server; 168 tool handlers (one Params struct + one #[tool] fn per tool)
  resolver/
    mod.rs, standard.rs, iterative.rs  — hickory-dns resolver wrappers
    zone_transfer.rs                   — AXFR logic
  error.rs      — ShoheError enum + Result<T> alias
  lib.rs        — crate root
tasks/          — project management (not compiled)

Module pattern

Every module follows the same shape:

// src/api/example.rs

use serde::{Deserialize, Serialize};
use crate::error::Result;
use crate::api::helpers::{validate_url_safety, build_http_client};

#[derive(Debug, Deserialize, Default)]
pub struct ExampleRequest {
    pub domain: String,
    #[serde(default = "default_timeout")]
    pub timeout_secs: u64,
}
fn default_timeout() -> u64 { 10 }

#[derive(Debug, Serialize)]
pub struct ExampleResult {
    pub domain: String,
    pub findings: Vec<String>,
    pub checked_at: String,
}

pub async fn check_example(req: &ExampleRequest) -> Result<ExampleResult> {
    validate_url_safety(&format!("https://{}", req.domain))
        .map_err(|e| crate::error::ShoheError::Parse(e))?;
    let client = build_http_client(req.timeout_secs)?;
    // ...
    Ok(ExampleResult { domain: req.domain.clone(), findings: vec![], checked_at: helpers::now_rfc3339() })
}