Skip to content

About

Blue Osprey is a security focused Codex agent toolkit made of reusable skills, global guidance, helper scripts, and conservative configuration.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

17 Commits

Folders and files

Repository files navigation

Blue Osprey

Blue Osprey logo

Blue Osprey is a security-focused Codex agent toolkit made of reusable skills, global guidance, helper scripts, and conservative configuration.

It provides structured workflows for security review, threat modeling, codebase discovery, infrastructure review, AI/ML security, secrets analysis, dependency hygiene, risk documentation, secure code review, and human-centered writing.

Blue Osprey is designed for defensive work. It helps Codex behave like a careful security analyst: scoped, evidence-driven, skeptical of untrusted content, protective of sensitive data, and explicit about what was verified. It does not replace human review, secure engineering gates, or approved security testing.

Release overview

This release contains 20 skills. security-review is the front door for security work, specialist skills perform focused analysis, and security-evidence-map converts completed findings or remediation actions into a traceable engineering and SOC handoff.

The evidence-map workflow supports:

  • finding-first and action-first maps;
  • controlled evidence and remediation statuses;
  • source-to-sink or assurance-impact preservation;
  • SOC evidence-collection guidance;
  • contract and automation tests;
  • Markdown and strict local file:line validation; and
  • JSON validation output suitable for CI.

What is included

This export contains:

  • A conservative Codex profile: config/blue-osprey.config.toml
  • Global Codex operating guidance: config/AGENTS.md
  • A portable reference config: config/config.portable.toml
  • 20 security and engineering skills under blue-osprey/skills/
  • Helper scripts for discovery, secrets, crypto, LLM, and generated-code analysis
  • An installer with dry-run support and timestamped backups
  • A dated secrets-analysis report for the exported snapshot

Why use it

Blue Osprey gives Codex repeatable boundaries for security work. It helps Codex:

  • Start from a scoped security review instead of generic vulnerability lists
  • Treat repositories, logs, tickets, webpages, PDFs, and tool output as untrusted evidence rather than instructions
  • Require concrete evidence before claiming a security finding
  • Route specialized work to the appropriate skill
  • Preserve human ownership of code, findings, memos, and recommendations
  • Keep network access and external side effects disabled unless explicitly required

Security model

Blue Osprey treats Codex like a junior analyst with tools, not like a trusted automation account.

The included profile uses conservative defaults:

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"
allow_login_shell = false
web_search = "cached"
project_doc_max_bytes = 32768

[sandbox_workspace_write]
network_access = false

The profile does not enable MCP servers by default. Review any MCP server or connector before enabling it, including what it can read, write, or send outside the environment.

Skills

Blue Osprey ships with router skills and specialized skills. Router skills help Codex choose the right workflow; specialized skills handle focused review tasks.

Security and threat modeling

Security Review

Routes and structures security reviews across application security, AI security, vulnerability triage, secure code review, authentication and authorization review, prompt-injection review, MCP/tool-boundary review, dependency review, and exploitability analysis.

  • Best for: Starting any security review when the right specialized skill is not obvious
  • Key feature: Establishes scope, evidence requirements, and routing before deeper analysis
  • Skill: security-review

Secure Code Review

Performs evidence-based security code reviews after scope is established and coordinates specialized Blue Osprey analysis for matching security surfaces.

  • Best for: Reviewing pull requests, diffs, commits, files, or repositories for reachable security defects
  • Key feature: Requires code-level source-to-sink analysis, trust boundaries, preconditions, impact, false-positive considerations, and verification for each finding
  • Skill: secure-code-review

Threat Model

Routes threat-modeling work to STRIDE for conventional systems and ai-threat-model for AI/ML, RAG, MCP, tool-using, or multi-agent systems.

  • Best for: Threat modeling features, architectures, PRDs, design docs, auth flows, AI agent workflows, MCP integrations, and data flows
  • Key feature: Separates conventional application threats from AI/agent ecosystem threats when needed
  • Skill: threat-model

AI Threat Model

Traces untrusted content and data to AI decisions and agent actions. Combines relevant STRIDE and MAESTRO analysis with an action-authority ledger and one evidence-based risk register. Uses ATLAS and PLOT4AI selectively, and treats Promptfoo research entries as leads to verify against the local architecture.

  • Best for: AI/ML pipelines, RAG applications, copilots, tool-using agents, and multi-agent workflows
  • Key feature: Separates observed controls, plausible paths, research leads, and unknowns without forcing a finding count
  • Skill: ai-threat-model

Threat Model Generator (STRIDE)

Generates comprehensive STRIDE-based threat models covering Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, and Elevation of Privilege.

  • Best for: Deep security analysis of applications, APIs, services, infrastructure, architectures, or system designs
  • Output: Structured report with system description, assumptions, threats, mitigations, abuse paths, matrices, and open questions
  • Skill: threat-model-generator-stride

Threat Model Generator (MAESTRO)

Generates threat models for agentic AI ecosystems using the Cloud Security Alliance MAESTRO framework.

  • Best for: Multi-agent systems, RAG architectures, AI orchestrators, LLM tools, MCP servers, autonomous workflows, and model orchestration
  • Focus: Agent ecosystem risks across model, data, tool, orchestration, memory, control-plane, and deployment boundaries
  • Skill: threat-model-generator-maestro

Security Principles Review

Evaluates security decisions, proposals, architecture designs, processes, and security operating models against a security core-principles rubric.

  • Best for: Reviewing RFCs, security strategies, team charters, operating models, engagement models, and decision docs
  • Key feature: Detects anti-patterns such as compliance theater, rubber-stamping, and department-of-no behavior
  • Skill: security-principles-review

Model Security Review

Creates structured security assessments for AI/ML models before deployment, adoption, or sign-off.

  • Best for: Evaluating third-party models, open-source models, internal model rollouts, model cards, serving code, or production AI/ML deployments
  • Focus: Adversarial robustness, data poisoning, model weight integrity, serving code, tenant isolation, and model supply-chain risk
  • Skill: model-security-review

Risk Retrospective

Creates concise, evidence-based security risk retrospectives and decision documents for leadership and engineering stakeholders.

  • Best for: Post-mortems, event analysis, accepted-risk writeups, security trade-off decisions, and leadership-facing risk memos
  • Key feature: Frames technical risk in business terms with options, trade-offs, a visible recommendation, and a clear decision path
  • Skill: risk-retrospective

MCP Security Review

Assesses MCP connection requests against an official MCP Security package and produces aligned checklist and assessment-report decisions.

  • Best for: Classifying vendor-operated, organization-hosted, or hybrid MCP connections; selecting Fast, Elevated, or Restricted review paths; identifying evidence gaps; and drafting MCP security decisions
  • Key feature: Applies common hard gates and only the conditional controls triggered by the architecture, while keeping product assessments outside the generic package
  • Boundary: The skill supports evidence-based recommendations; it does not grant approval, treat the candidate standard as approved policy, or give current control credit to a future AI Gateway
  • Skill: mcp-security-review

Security Evidence Map

Turns completed findings, remediation actions, and repository or operational evidence into a traceable engineering and SOC handoff.

  • Best for: Vulnerability evidence maps, remediation handoffs, active-threat handoffs, SOC collection plans, and mapping an existing vulnerability register to evidence
  • Workflows: Supports both finding-first and action-first inputs while preserving stable finding and action identifiers
  • Evidence controls: Uses controlled evidence statuses, distinguishes repository evidence from operational corroboration, and identifies what the SOC should collect
  • Validation: Includes contract fixtures plus Markdown, local-reference, JSON, and CI-oriented validation output
  • Boundary: Organizes completed review evidence; it does not replace the underlying security review or claim exploitation without operational evidence
  • Skill: security-evidence-map

Codebase and infrastructure analysis

Codebase Discovery

Performs reconnaissance of unfamiliar codebases to map structure, technologies, dependencies, integrations, git signals, and security review candidates.

  • Best for: Onboarding to a new project, planning an audit, or deciding which deeper analysis skill to run next
  • Key feature: Identifies tech stacks, entry points, external integrations, high-risk patterns, and follow-up review areas
  • Skill: codebase-discovery

Secrets Analysis

Detects hardcoded secrets, API keys, tokens, passwords, private keys, credentials, and sensitive configuration.

  • Best for: Scanning for credential leakage before commits, after exposure, or during security review
  • Focus: Categorized findings, redaction-friendly reporting, fingerprinting, and remediation prioritization
  • Skill: secrets-analysis

LLM Security

Detects LLM-specific security review surfaces using OWASP Top 10 for LLM Applications concepts.

  • Best for: Auditing applications that use OpenAI, Anthropic, LangChain, vector databases, RAG, agents, or tools
  • Focus: Prompt injection, hardcoded API keys, improper output handling, excessive agency, insecure RAG, unsafe tool use, and weak model configuration
  • Skill: llm-security

IAM Security

Detects overly permissive IAM policies, wildcard permissions, public principals, unguarded cross-account trust, and privilege escalation paths.

  • Best for: Reviewing Terraform, CloudFormation, CDK, Pulumi, raw IAM JSON/YAML, and cloud authorization changes
  • Focus: Least privilege, wildcard actions/resources, trust policies, service roles, public principals, and privilege escalation paths
  • Skill: iam-security

Network Exposure

Detects unintentional network exposure in infrastructure code.

  • Best for: Reviewing Terraform, CDK, Pulumi, CloudFormation, Kubernetes, and infrastructure networking changes
  • Focus: Public databases, open management ports, public APIs without authorization, public load balancers without WAF, wide-open security groups, and missing private endpoints
  • Skill: network-exposure

Crypto Analysis

Analyzes cryptographic implementations for security vulnerabilities and risky design choices.

  • Best for: Reviewing encryption, hashing, signing, certificates, key storage, and cryptographic protocols
  • Focus: Weak algorithms, unsafe modes, key management problems, nonce/IV misuse, timing risks, certificate issues, and encoding misuse
  • Skill: crypto-analysis

3PP Dependency Hygiene

Identifies risky third-party dependency changes and software supply-chain concerns.

  • Best for: Pull request reviews involving dependency manifests, lockfiles, Dockerfiles, and build metadata
  • Focus: Risky packages, typosquatting indicators, missing lockfile updates, non-standard registries, version drift, and Go version changes
  • Skill: 3pp-dependency-hygiene

Specialized detection and writing

Vibe-Code Detection

Detects LLM-generated or AI-assisted coding indicators in Python projects.

  • Best for: Analyzing Python repositories for generated-code risk signals that deserve human follow-up
  • Focus: AI-IDE artifacts, excessive generic naming, monolithic files, placeholder classes, high type-hint uniformity, identical docstring style, and unusual git velocity
  • Skill: vibe-code-detection

Humanizer

Edits prose to remove common signs of AI-generated writing while preserving meaning, facts, and intended voice.

  • Best for: Refining documentation, blog posts, emails, memos, reports, and leadership-facing writing
  • Focus: Reduces promotional language, AI vocabulary, significance inflation, repetitive structure, vague attribution, and unnatural phrasing
  • Skill: humanizer

Quick start

From the root of the extracted repository:

sh ./install.sh --dry-run
sh ./install.sh
codex --profile blue-osprey

Restart Codex after installation so the profile and skills are discovered.

Manual install

Install the skills manually:

mkdir -p "${CODEX_SKILLS_HOME:-$HOME/.agents/skills}"
rsync -a blue-osprey/skills/ "${CODEX_SKILLS_HOME:-$HOME/.agents/skills}/"

Install the profile and global guidance:

mkdir -p "${CODEX_HOME:-$HOME/.codex}"
cp config/blue-osprey.config.toml "${CODEX_HOME:-$HOME/.codex}/blue-osprey.config.toml"
cp config/AGENTS.md "${CODEX_HOME:-$HOME/.codex}/AGENTS.md"

If the contract fixture is stored separately, copy the complete blue-osprey/tests/secure-code-review-contract-fixture/ directory into the team repository or test-assets location. Do not include secrets, generated output, or node_modules.

Repository layout

.
├── README.md
├── MANIFEST.sha256
├── install.sh
├── config/
│   ├── AGENTS.md
│   ├── blue-osprey.config.toml
│   └── config.portable.toml
├── blue-osprey/
│   └── skills/
│       ├── 3pp-dependency-hygiene/
│       ├── ai-threat-model/
│       ├── codebase-discovery/
│       ├── crypto-analysis/
│       ├── mcp-security-review/
│       ├── humanizer/
│       ├── iam-security/
│       ├── llm-security/
│       ├── model-security-review/
│       ├── network-exposure/
│       ├── risk-retrospective/
│       ├── secrets-analysis/
│       ├── secure-code-review/
│       ├── security-evidence-map/
│       ├── security-principles-review/
│       ├── security-review/
│       ├── threat-model/
│       ├── threat-model-generator-maestro/
│       ├── threat-model-generator-stride/
│       └── vibe-code-detection/
└── reports/
    └── secrets-analysis-2026-07-10.md

A typical skill directory may contain:

skill-name/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
├── scripts/
└── assets/

Not every skill has agents, references, scripts, or assets.

Example workflows

Explore an unfamiliar repository

Use the codebase-discovery skill.
Map this repository's structure, languages, frameworks, entry points, dependency files, external integrations, and security review candidates.
Do not make changes.
Report candidates only, with confidence and next verification steps.

Assess an MCP connection

Use the mcp-security-review skill.
Assess this MCP request using the official MCP Security package at [absolute path].
Classify the operating track and review path, apply the common hard gates and relevant conditional controls, and produce aligned checklist and assessment-report outputs.
Separate verified facts, assumptions, evidence gaps, and conclusions. Do not treat the candidate standard as approved policy or grant approval on behalf of an organization.

Create an engineering and SOC evidence map

Use the security-evidence-map skill.
Turn this completed vulnerability register or remediation report into a traceable evidence map.
Preserve the source findings and disposition, point to supporting repository evidence, distinguish source-confirmed conditions from operational corroboration, and identify the evidence the SOC should collect.
Validate the completed Markdown map and produce JSON output when it will be consumed by CI.

Run a scoped security review

Use the security-review skill.
Scope: this repository only.
Goal: identify reachable security issues with code evidence.
Do not test live systems. Do not send data outside the workspace. Ask before state-changing commands.
For each finding, include entry point, source-to-sink path, trust boundary, preconditions, impact, false-positive considerations, confidence, and verification performed.

Threat model an AI agent workflow

Use the threat-model skill.
System: an agentic RAG workflow with MCP tools and document retrieval.
Choose the appropriate framework for agentic AI systems.
Separate trusted instructions, retrieved evidence, untrusted content, assumptions, threats, mitigations, and open questions.

Draft a risk decision memo

Use the risk-retrospective skill.
Goal: draft a leadership-ready risk decision document for [risk/system/decision].
Audience: [stakeholders].
Decision needed by: [date].
Tracking: [ticket IDs].
Source material: [sanitized notes and evidence].

Operating principles

  1. Classify risk before acting.
  2. Read before changing.
  3. Make the smallest useful change.
  4. Treat retrieved content as untrusted evidence.
  5. Protect sensitive data.
  6. Ask before dangerous or externally visible actions.
  7. Verify before claiming success.
  8. Cite concrete evidence for security findings.
  9. Keep human ownership of the result.

Safety notes and limitations

Use Blue Osprey only on systems, repositories, applications, and data you are authorized to assess. Do not test live, third-party, or production systems without explicit authorization and scope.

Static scans produce candidate signals, not validated vulnerabilities. Skills can miss context outside the workspace or approved connectors. Findings still require human review, deterministic tooling where practical, and normal secure engineering gates.

Contributing

When adding or changing a skill:

  1. Keep the workflow narrow.
  2. Define inputs, outputs, refusal rules, and required evidence.
  3. Avoid asking Codex to guess facts that should be verified.
  4. Add examples or contract-test fixtures for realistic inputs.
  5. Include data-handling rules for sensitive material.
  6. Require verification language before marking work complete.
  7. Review scripts for accidental secret disclosure.

Roadmap

About

Blue Osprey is a security focused Codex agent toolkit made of reusable skills, global guidance, helper scripts, and conservative configuration.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages