bmad+
Menu
ENChoose language
Get started
Browse the documentation

OSINT pack: Shadow, governed public-source research

Shadow runs a phased open-source investigation with a mandatory lawful-basis gate for named people. Install, API keys, budget rule, seven prompts, outputs and legal limits.

On this page
  1. When to use it
  2. What is installed
  3. Quick start
  4. Copyable examples
  5. What it writes and where
  6. Data flows and prerequisites
  7. Limits and gotchas

The OSINT pack installs Shadow, an agent that turns a name, a handle or a company into a graded research dossier using public sources (OSINT means open-source intelligence). It chains quick searches, source verification, social-media extraction through Apify scrapers and cross-referencing, and it always escalates from cheap and fast to expensive and deep. Because researching a named person is processing of personal data, the pack is governed: Shadow must record a lawful basis and a purpose before it touches anyone identifiable.

Warning Read this before you use it on a person

You are the data controller, not BMAD+. Investigating an identifiable person needs a documented lawful basis (GDPR Article 6, and an Article 9(2) condition for personality or other special-category inference) before the first request. Scraping may breach a platform’s terms of service. Output is AI-generated, can be wrong and needs human verification before any decision. This page is not legal advice.

When to use it

  • Due diligence on a supplier, partner or counterpart, with a stated purpose and legal basis.
  • Company, product or market research: it needs no lawful-basis gate because no natural person is profiled.
  • Security research or a mandated investigation, where the mandate and basis are explicit and auditable.
  • Not for curiosity about a private individual, harassment, or profiling a neighbour, ex-partner, employee or applicant without a basis. Shadow declines those.

What is installed

One agent, Shadow, in .agents/skills/agent-shadow/, plus two skills copied from the bundled package osint-agent-package into .agents/skills/: bmad-osint-investigate (the investigation pipeline and its provider scripts) and bmad-osint-investigator (a second entry point inherited from the package; it loads _bmad/bmm/agents/osint-investigator.md, a file a BMAD+ install does not create, so start from Shadow). The registry lists no separate skills for this pack; the two above come from the package. Shadow’s menu names prompt files for QS, LI, IG, FB, PP, CE and DG that the package does not ship: those entries run from the menu line and from the pipeline instructions in bmad-osint-investigate.

Shadow menu
CodeCapabilityLawful-basis gate
INVFull investigation, phases 0 to 6, scored dossierYes, for a named person
QSQuick multi-engine search on a name or handleNo for a public handle
LI / IG / FBLinkedIn, Instagram, Facebook public profile extraction through ApifyYes
PPPersonality profile (MBTI, Big Five)Yes, plus an Article 9 condition
CEContact enrichment: email, phone, contact detailsYes
DGDiagnose which APIs and tools are availableNo

The investigation phases

  1. Phase -1, lawful-basis gate: record the basis, the purpose, the controller, the retention period and how access or erasure requests are honoured. No basis, no named-person work.
  2. Phase 0, tooling self-check: run the diagnostic and note which tools and keys are missing.
  3. Phase 1, seed collection: cheap searches first, then verify the cited sources and merge identifiers.
  4. Phase 1.5, internal intelligence: look at what you already hold (conversation history, email, a local contact vault) when such tools are configured, before going external.
  5. Phase 2, platform extraction: structured social-media data through Apify scrapers.
  6. Phase 3, cross-reference and confidence scoring: fact table, cross-checks, contradictions, name collisions.
  7. Phase 4, psychoprofile, only with the extra legal condition.
  8. Phase 5, completeness evaluation: coverage, depth score, source diversity, stop criteria.
  9. Phase 6, dossier output from the template, with depth score, source count and total spend.

Quick start

  1. Install the pack

    Core is added automatically. Python 3.10 or newer must be available on the machine that runs the scripts.

    In your project terminal
    npx bmad-plus install --packs osint

  2. Set at least one API key as an environment variable

    One key is enough to start; Jina is the suggested first one. Never write a key into a file of the project. The names Shadow reads are JINA_API_KEY, APIFY_API_TOKEN, PERPLEXITY_API_KEY, EXA_API_KEY, TAVILY_API_KEY, PARALLEL_API_KEY and BRIGHTDATA_MCP_URL.

    In your project terminal
    $env:JINA_API_KEY = "your-key"

  3. Ask Shadow what is available

    The diagnostic touches no personal data and tells you which providers answer.

    In your project terminal
    Shadow, diagnose which OSINT tools and APIs are available.

Copyable examples

Check the toolbox first (DG)

Run it right after setting your keys. It is exempt from the lawful-basis gate.

In your AI assistant
Shadow, diagnose which OSINT tools and APIs are available.

What you should get A capability map of the search and scraping providers: which keys are set, which are missing and what that limits (for example, without Apify the structured social-media data is limited).

Research a company, not a person

Company research needs no lawful-basis gate. Name what you want to decide with the result, and name the output folder: the package ships two conventions (see What it writes and where).

In your AI assistant
Shadow, run INV on the company Acme Ltd, a legal entity and not a person: legal form, activity, public filings, press mentions and published sanctions or litigation. I want to decide whether to onboard it as a supplier. Save the dossier in _bmad-output/osint-reports/, grade every fact and list what you could not verify.

What you should get A dossier on the company, saved where you asked (_bmad-output/osint-reports/), with a grade from A to D on every fact (Shadow tells you which scale it applies) and the list of what could not be verified. Shadow states the source quality and its limits, and tells you the cost as it goes; it spends up to 0.50 dollars without asking and asks above that.

Full investigation with a recorded basis (INV)

State the purpose, the basis and the retention up front; Shadow records them before it searches.

In your AI assistant
Shadow, run a due-diligence check on the managing director of supplier Acme Ltd, Jane Doe. Purpose: supplier onboarding. Basis: legitimate interest, balancing test noted in our onboarding file. Controller: Acme Client. Retention: 12 months. Data-subject requests go to privacy@acme-client.example. Save the dossier in _bmad-output/osint-reports/.

What you should get Phase -1 comes first: the basis, purpose, controller and retention are recorded from the lawful-basis template. The dossier then opens with the governance block and the notice that the output is AI-generated, may contain errors, is not legal advice and needs human verification. It is saved in the folder you named (here _bmad-output/osint-reports/), with the target and date in the name as Shadow’s agent file asks.

Extract a public LinkedIn profile (LI)

Needs the Apify token and the lawful-basis gate. Give the whole basis in the request: Shadow can only read what is in the conversation or in the project. Scraping can breach the platform’s terms; check them first.

In your AI assistant
Shadow, extract the public LinkedIn profile https://www.linkedin.com/in/jane-doe-example for the Acme Ltd onboarding file. Purpose: supplier onboarding. Basis: legitimate interest, balancing test noted in our onboarding file. Controller: Acme Client. Retention: 12 months. Data-subject requests go to privacy@acme-client.example. Report the cost before you run the scraper.

What you should get Shadow checks that the basis, purpose, controller and retention are recorded, then runs the Apify scraper for that profile and adds the structured data to the dossier. Above 0.50 dollars of cumulative spend it stops and asks you.

What a request without a basis gets (PP)

This prompt states no purpose and no basis, on purpose: it shows the gate working.

In your AI assistant
Shadow, build a personality profile of my new neighbour, Jane Doe. Find everything you can.

What you should get Shadow declines the named-person profiling: an open-ended find-everything request has no specific purpose, no Article 6 basis and no Article 9 condition for personality inference. It offers the non-personal alternatives, such as company, product or market research, or an investigation of a public entity.

Contact enrichment for a business contact (CE)

Use it with a stated purpose, for example answering a partner who contacted you.

In your AI assistant
Shadow, find the professional email and phone of the sales director of Acme Ltd, as listed on public sources. Purpose: reply to their partnership request. Basis: legitimate interest. Controller: Acme Client. Retention: 6 months. Data-subject requests go to privacy@acme-client.example.

What you should get The gate record comes first (basis, purpose, controller, retention, how requests are honoured). Contact details are then looked up in public sources and graded A to D; Shadow tells you which scale it applies and marks the details that only one source supports.

What it writes and where

  • Dossier folder: Shadow’s agent file says _bmad-output/osint-reports/, named with the target and the date (the folder follows the output_folder setting of _bmad/config.yaml), while the instructions of the investigation skill say recherches/personnes-physiques/<name>.md or recherches/personnes-morales/<name>.md in the project root, without a date. The package ships both instructions, so name the folder in your request to get the one you want.
  • The lawful-basis record, from the template assets/lawful-basis-record.md, sits at the top of the dossier.
  • Grades: every fact gets A, B, C or D. Shadow’s agent file defines them by source count (A three or more sources, B two, C one, D unverified); the pipeline file defines them by evidence (A confirmed by two or more independent sources or an official profile, B one credible source, C inferred, D unverified). Ask Shadow which scale it used and read each grade next to its listed sources.

Data flows and prerequisites

  • Off-machine flow osint-providers: Shadow’s scripts call Apify, Exa, Jina, Parallel, Perplexity, Tavily and Bright Data over HTTPS, with your own keys. Consent basis: the credential you set. What you ask about leaves your machine as a query to those providers.
  • Keys: none is required. Each provider script checks only its own key, so one key from any provider is enough to start. The scripts read APIFY_API_TOKEN (the social-media scrapers), PERPLEXITY_API_KEY, EXA_API_KEY, TAVILY_API_KEY, JINA_API_KEY, PARALLEL_API_KEY and BRIGHTDATA_MCP_URL; the registry lists them all as optional.
  • Prerequisites: Python 3.10 or newer; the scripts use only the Python standard library, no extra package.
  • Costs are on your accounts. Shadow tracks spending per session and asks above 0.50 dollars per target.

Limits and gotchas

Warning Phase 1.5 can read your own mail and chats

Before going external, the pipeline checks internal sources such as conversation history, email and a local contact vault when tools for them are configured. If you do not want that, say so in the request or do not configure those tools. Internal findings go in a separate section marked internal and confidential.

Note Provider scripts

The package ships its provider scripts as Python files (apify.py, exa.py, jina.py, perplexity.py, tavily.py, brightdata.py, parallel.py, volley.py, diagnose.py) that use only the Python standard library. Run them with Python 3.10 or newer.

Note Provenance

The investigation pipeline is adapted from an MIT-licensed open-source skill, and the Apify runner draws on Apify’s agent skills (Apache-2.0). The exact notices are in THIRD-PARTY-LICENSES.md of the package.

See also