# Lookup Greynoise

> Use when you need to classify an IP as internet scanner noise vs. targeted activity. Returns noise/riot flags, classification (benign/malicious/unknown), actor name if known. IP-only. Commonly invoked by /ip-investigation to filter out mass-scanning noise. Retrieval only.

- **Type:** Skill
- **Install:** `agentstack add skill-liberty91ltd-cti-skills-lookup-greynoise`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Liberty91LTD](https://agentstack.voostack.com/s/liberty91ltd)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Liberty91LTD](https://github.com/Liberty91LTD)
- **Source:** https://github.com/Liberty91LTD/cti-skills/tree/main/skills/lookup-greynoise
- **Website:** https://liberty91.com/cti-skills

## Install

```sh
agentstack add skill-liberty91ltd-cti-skills-lookup-greynoise
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# lookup-greynoise

Queries GreyNoise to classify whether an IP is internet background noise (opportunistic scanners, search engines, etc.) or targeted. IP-only. Retrieval only.

## When to invoke

- User asks if an IP is scanner noise or targeted
- Investigation skill wants to filter out mass-scanning IPs from indicator lists
- Deciding if an IP hitting your perimeter is worth investigating

## How to invoke

Two CLIs are provided. Pick by capability needed:

### Basic noise check — Node CLI (zero deps)

```bash
node tools/clis/greynoise.js ip 
```

Hits the `/v3/community/{ip}` endpoint (free, 50/day). Best for fast retrieval inside an investigation chain.

### Full surface — Python CLI (uses official pygreynoise SDK)

```bash
python3 tools/clis/greynoise.py community           # FREE (50/day)
python3 tools/clis/greynoise.py context             # Enterprise
python3 tools/clis/greynoise.py riot                # Enterprise
python3 tools/clis/greynoise.py quick        # Enterprise (bulk)
python3 tools/clis/greynoise.py similarity          # Enterprise
python3 tools/clis/greynoise.py timeline  [--days N]  # Enterprise
python3 tools/clis/greynoise.py query ""          # Enterprise
python3 tools/clis/greynoise.py stats ""          # Enterprise
python3 tools/clis/greynoise.py metadata
```

Self-bootstraps a private venv at `tools/clis/.venv-greynoise/` on first run.

Capabilities the Node CLI doesn't have (Enterprise tier required for most):

1. **Context** — full per-IP telemetry: every port/protocol/payload combination GreyNoise has observed, broken down by date.
2. **GNQL search** (`query`) — find every IP matching a query: `classification:malicious tags:Mirai metadata.country:RU`. The killer pivot — discover scanner clusters by characteristic.
3. **GNQL stats** — bucket counts (countries, ASNs, tags, categories) for a query without pulling individual results.
4. **Similarity** — given an IP, find behaviorally similar scanners (often used to expand a single observation into a cluster).
5. **Timeline** — daily activity history for an IP — useful for distinguishing a brief campaign from persistent scanning.
6. **Quick (bulk)** — classify many IPs in one call (cheaper than N individual lookups).
7. **RIOT** — explicit known-benign check (CDNs, search engines, ISPs) without the noise classification.

GNQL examples:
```bash
# All malicious scanners hitting port 22 from Russia in the last day
python3 tools/clis/greynoise.py query 'classification:malicious raw_data.scan.port:22 metadata.country:RU last_seen:1d'

# Stats: country distribution of Mirai-tagged IPs
python3 tools/clis/greynoise.py stats 'tags:"Mirai" last_seen:30d'

# Find IPs similar to a known scanner
python3 tools/clis/greynoise.py similarity 185.220.101.45 --limit 50
```

Both CLIs accept `--dry-run`.

### Tier awareness — this matters

- **Community endpoint** (`/v3/community/{ip}`) is **public and unauthenticated**. Both CLIs work without `$GREYNOISE_API_KEY` for the `community` subcommand. Rate-limited per source IP (a few per minute is fine; sustained bulk lookups will throttle).
- **Enterprise endpoints** (context, RIOT, GNQL, similarity, timeline, quick) require a paid Enterprise key. As of 2026 GreyNoise no longer offers a free community API key tier — what their portal calls an "API key" gates Enterprise access. The CLIs return a 401 / 402 / "upgrade required" error if your key doesn't have access; fall back to `community`.
- The community endpoint is sufficient for the most common CTI question — "is this IP a known scanner?" — for most investigation use.

## Response format

```yaml
source: greynoise
indicator: 
query_time: 
noise:           # seen as internet background noise
riot:            # rule-it-out: known-benign common service
classification: benign | malicious | unknown
name: 
last_seen: 
message: 
```

## Rate limits

Community endpoint: 50 req/day free. Enterprise: much higher.

## Source reliability (Admiralty default)

Default rating for downstream `/score-source`: **B2** (usually reliable, probably true). Empirical signal. A `noise: true` result is strong evidence the IP is not targeted.

## Operational notes

- IP addresses only. The CLI rejects non-IP inputs.
- `riot: true` is a strong signal the IP is a benign common service (CDN, search engine, etc.) — downgrade severity of any detection against it.
- `classification: malicious` + `noise: true` = mass-scanning threat actor infrastructure, not a targeted campaign.

## Related skills

- `/lookup-abuseipdb` — abuse reports for the same IP
- `/lookup-virustotal`, `/lookup-shodan` — additional IP context
- `/ip-investigation` — uses GreyNoise to filter noise early in the pipeline

## See also

- Integration setup: `tools/integrations/greynoise.md`
- Node CLI source: `tools/clis/greynoise.js`
- Python CLI source: `tools/clis/greynoise.py`
- Official Python SDK: https://github.com/GreyNoise-Intelligence/pygreynoise
- API docs: https://docs.greynoise.io/
- GNQL syntax: https://docs.greynoise.io/docs/using-the-greynoise-query-language-gnql

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Liberty91LTD](https://github.com/Liberty91LTD)
- **Source:** [Liberty91LTD/cti-skills](https://github.com/Liberty91LTD/cti-skills)
- **License:** MIT
- **Homepage:** https://liberty91.com/cti-skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-liberty91ltd-cti-skills-lookup-greynoise
- Seller: https://agentstack.voostack.com/s/liberty91ltd
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.