Introduction

Welcome back, amigos! I’ve been wanting to create more projects around AI Agents to show what’s possible when we move beyond simple chatbots. This is the first in a series of "Agentic Blueprints" that you can use as a starting point. Think of this as a modular template: you can use it exactly as it is, or you can pick out the specific sections that work for you and adapt them to your own security needs.

If you are new to cybersecurity or just starting to explore AI agents, this is meant to be the perfect "Day 1" project. In 2025, being a security practitioner isn't just about reading logs; it's about building the automated systems that help you stay ahead of the curve. More and more of us are running into situations where we need to do more with less and AI agents can be a great way to help you bridge that gap.

Low Barrier to Entry: I purposefully built and tested this entire project from start to finish on an iPad. Because we are using cloud-based resources, you don't need a high-end workstation. If you have a web browser, you can build this CTI workbench.

Disclaimer: This project is a personal exercise intended for educational purposes. It does not represent the official position, security strategies, or endorsements of any organization I am affiliated with. Use this tool responsibly and always cross-verify AI-generated intelligence.

What You Will Learn

In this project, you will move beyond basic prompting and learn how to:

• Architect a Multi-Agent System: Break a complex security mission into specialized roles using CrewAI.

• Manage AI Hallucinations: Use a "Senior Validator" agent to fact-check findings and ensure technical precision.

• Implement Dynamic CTI Logic: Use Python to force agents to hunt for the most recent threat data, avoiding stale or irrelevant results.

• Practice Secure Development: Use Colab Secrets to manage API keys, preventing common security mistakes like hardcoding credentials.

The Design

The goal here is to build a Structured Intelligence Workbench.

You might be wondering: "Why not just give a single, detailed prompt to Gemini?" While beefy prompts are great for simple tasks, they often struggle with complex tasks like synthesizing Threat Intel. When you ask a single AI to search the web, extract technical CVEs, write an executive summary, and verify the facts all at once, the logic tends to break down. Sometimes you get "hallucinations" or generic fluff.

By using Agents, we break that process into a specialized workflow. Each agent has one job:

• The Hunter only cares about finding the raw data.

• The Architect only cares about the structure and remediation logic.

• The Validator only cares about accuracy.

This modular approach mimics how a real-world security team might work, leading to much higher quality data that you can actually trust.

The Stack

• Google Gemini 2.5 Flash: We chose "Flash" because it is optimized for high-speed, agentic tasks where large amounts of raw data must be processed quickly.

• CrewAI: This framework allows us to define specific backstories and goals, forcing the AI to maintain the skepticism and methodology of a senior security professional.

• LangChain: We use this as a "Universal Adapter." It makes it easy to swap Gemini for another model later without rewriting your entire project.

What You Need

Before we touch any code, we need to gather our keys.

1. Google Gemini API Key: Go to Google AI Studio. Sign in, click "Get API Key," and create one. This is free and acts as the "brain" power for your project.

2. Serper.dev API Key: Go to Serper.dev and sign up for a free account. This gives your agents the ability to search Google for live data.

Open Your Lab Notebook

We are using Google Colab, a free tool that runs Python in your browser.

1. Go to colab.research.google.com.

2. Click "New Notebook."

3. This notebook is made of Cells. For each phase below, you will click the "+ Code" button to create a new cell, paste the code, and hit the Play (▶️) button to run it.

Building Our Code

Phase 1: Environment Installation

First, we need to install our frameworks. We use the -q flag to keep the installation quiet and suppress unnecessary logs.

# Install the framework, the Google Gemini integration, and search tools
!pip install -q -U crewai crewai[tools] langchain-google-genai

Note: You may see red "dependency conflict" errors like the image below. Colab has its own pre-installed versions of certain libraries; these errors are safe to ignore as our workbench will prioritize its own requirements.

Phase 2: Secure API Configuration

Hardcoding API keys is one of the most common security mistakes in development. If you paste your key directly into the code, anyone with access to the notebook (or your version history) can steal it. We use Colab's Secrets feature (the key icon 🔑 on the left sidebar) to store our keys externally.

1. Click the Key Icon.

2. Add GOOGLE_API_KEY and SERPER_API_KEY.

3. Toggle the "Notebook Access" switch to ON.

import os
from google.colab import userdata
from langchain_google_genai import ChatGoogleGenerativeAI

# Configure API Keys from Colab Secrets - NEVER hardcode these!
os.environ["GOOGLE_API_KEY"] = userdata.get('GOOGLE_API_KEY')
os.environ["SERPER_API_KEY"] = userdata.get('SERPER_API_KEY')

# Initialize Gemini 2.5 Flash
# We use max_retries and a lower temperature for consistent, factual CTI data
gemini_llm = ChatGoogleGenerativeAI(
    model="gemini-2.5-flash",
    temperature=0.1,
    google_api_key=os.environ["GOOGLE_API_KEY"],
    max_retries=5
)

Phase 3: Declaring the Agents

This section defines the specialized roles. Rather than just giving them titles, we provide them with a Goal and a Backstory. We also use Dynamic Date Logic to ensure the agents stay focused on what is happening now.

Note: According to the CrewAI Agent Documentation, these core attributes are defined as:

• Goal: The individual objective that guides the agent’s decision-making.

• Backstory: Provides context and personality to the agent, enriching interactions.

from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool
from datetime import datetime, timedelta

# --- DYNAMIC DATE LOGIC ---
current_date = datetime.now()
current_month_year = current_date.strftime("%B %Y")
last_month_year = (current_date.replace(day=1) - timedelta(days=1)).strftime("%B %Y")

search_tool = SerperDevTool()

# 1. THE LEAD THREAT HUNTER (Collection Specialist)
hunter = Agent(
  role='Senior CTI Collection Specialist',
  goal=f'Extract raw technical intelligence on {{topic}} for {current_month_year}',
  backstory=f'''You are a veteran SOC analyst. You excel at identifying
  "patterns of life" in cyberattacks. You don't just find headlines; you find
  the specific TTPs, CVEs, and Indicators of Compromise (IOCs) that a
  practitioner needs to build a defense.''',
  tools=[search_tool],
  llm=gemini_llm,
  max_iter=4,
  max_rpm=10,
  verbose=True
)

# 2. THE SECURITY ARCHITECT (The Intelligence Designer)
architect = Agent(
  role='Security Operations Architect',
  goal='Convert raw intel into a structured, dual-layer intelligence report',
  backstory='''You turn raw data into actionable intelligence. You understand
  that managers need summaries, but engineers need data. You focus on
  structured lists, technical precision, and remediation logic.''',
  llm=gemini_llm,
  verbose=True
)

# 3. THE SENIOR VALIDATOR (The Quality Auditor)
validator = Agent(
  role='Senior Security Auditor',
  goal='Ensure all technical data is accurate, dated 2025, and high-fidelity.',
  backstory='''You are the final gatekeeper. You verify all CVE IDs,
  Threat Actor names, and TTPs against the raw findings. You ensure
  the final report is professional and free of AI hallucinations.''',
  llm=gemini_llm,
  verbose=True
)

Phase 4: Defining the Mission and Workflow

Tasks define our "Definition of Done." By using specific "Must-Haves" like CVE IDs and MITRE techniques we ensure the agents find actual data instead of writing a generic summary. We use a sequential process to ensure a professional "hand-off" between roles.

Note: For more on how to structure complex tasks, visit the CrewAI Task Documentation. According to the docs:

• Description: A clear, concise statement of what the task entails.

• Expected Output: A detailed description of what the task’s completion looks like.

Finally, we declare the Crew to pull everything together. We use process=Process.sequential so the output of one task serves as the context for the next.

# --- THE HIGH-FIDELITY TASKS ---

task1 = Task(
  description=f'''Conduct a deep-dive search for threats related to {{topic}}.
  FOCUS PERIOD: {last_month_year} to {current_month_year}.

  YOU MUST SEARCH FOR AND EXTRACT:
  - **Vulnerabilities**: Specific CVE IDs and their CVSS severity scores.
  - **Threat Actors (TA)**: Names or aliases (e.g., APT28, Storm-1811).
  - **Technical TTPs**: At least 3 MITRE ATT&CK techniques used.
  - **Indicators (IOCs)**: Malicious domains, IP ranges, or file hashes mentioned.
  - **Impact**: What exactly happens if this exploit succeeds?''',
  expected_output='A raw technical intelligence brief with verified links.',
  agent=hunter
)

task2 = Task(
  description='Organize the hunter\'s findings into a structured CTI Report.',
  expected_output='''A Markdown document structured exactly as follows:

  # 🛡️ CTI Report: [TOPIC]

  ## 1. Executive Summary
  - **Overview**: A 2-3 sentence high-level summary of the threat.
  - **Risk Rating**: (Critical/High/Medium/Low) and why.

  ## 2. Technical Intelligence
  - **Vulnerabilities**: List of CVEs and affected software versions.
  - **Adversary Profile**: Known Threat Actors and their motives.
  - **TTPs**: Bulleted list of MITRE ATT&CK techniques.
  - **IOCs**: Any specific IPs, domains, or hashes found.

  ## 3. Defensive Playbook
  - **Detection**: How to find this in your logs.
  - **Mitigation**: Immediate steps to block or patch.
  - **Adaptation**: How a user can tailor this to their specific environment.''',
  agent=architect
)

task3 = Task(
  description=f'''Audit the Intelligence Report for precision.
  1. Confirm all data points are from {last_month_year} or {current_month_year}.
  2. Cross-check the 'IOCs' and 'CVEs' against the Hunter's raw notes.
  3. Ensure the Executive Summary is concise and the Technical section is detailed.''',
  expected_output='A finalized, fact-checked CTI Intelligence Report.',
  agent=validator
)

# The Full CTI Workbench Crew
cti_crew = Crew(
  agents=[hunter, architect, validator],
  tasks=[task1, task2, task3],
  process=Process.sequential
)

Phase 5: The Intelligence Console

This cell turns your code into a tool. You can change the topic_query and hit play to run a new search as often as you like. The code handles the reporting and the timestamps for you.

# @title 🛡️ 2025 CTI Intelligence Console
# @markdown Type a topic below (e.g., 'Google Chrome', 'Microsoft Teams', 'Amazon Scams')
topic_query = "React2Shell" # @param {type:"string"}

if topic_query:
    print(f"🕵️ Hunter is checking {current_month_year} intelligence for: {topic_query}...\n")
    result = cti_crew.kickoff(inputs={'topic': topic_query})

    from IPython.display import Markdown
    print("\n" + "="*80)
    print(f"   LATEST THREAT INTELLIGENCE REPORT: {topic_query.upper()}")
    print(f"   GENERATED: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
    print("="*80 + "\n")
    display(Markdown(str(result)))
else:
    print("Please enter a topic to continue.")

Operating Your Workbench

The Importance of Sequential Execution

A Google Colab notebook follows a strict order of execution.

• State Persistence: When you run a cell, Python "remembers" the variables and agents you defined.

• The "Chain" Rule: If you try to run Phase 5 before Phase 3, the code will break because the console won't know what a "hunter" or "architect" is.

• Best Practice: If you restart, select Runtime > Run all to re-initialize everything from the beginning.

Using the Interactive Console

In Phase 5, you'll notice a user-friendly form on the right side of the cell. Simply type a new threat topic into the text box and click Play (▶️). The "Hunter" will immediately start a fresh search, and the "Validator" will audit the new findings.

What's Next?

This blueprint is your starting point. Because it’s modular, you can take what you need and leave the rest. Try adding a new agent that specializes in writing YARA rules based on the findings or connect it to a Slack webhook for automated alerts. Check back soon for our next agentic project. If you want to check out my completed lab notebook, I have linked it below.

Completed Colab Notebook: https://colab.research.google.com/drive/1fYqd3s68ejdgsPNo1wG9OBSFsuccLb2G?usp=sharing