## File: README.md [](https://www.spiderfoot.net/r.php?u=aHR0cHM6Ly93d3cuc3BpZGVyZm9vdC5uZXQv&s=os_gh) [](https://raw.githubusercontent.com/smicallef/spiderfoot/master/LICENSE) [](https://www.python.org) [](https://github.com/smicallef/spiderfoot/releases/tag/v4.0) [](https://github.com/smicallef/spiderfoot/actions?query=workflow%3A"Tests") [](https://github.com/smicallef/spiderfoot/commits/master) [](https://codecov.io/github/smicallef/spiderfoot) [](https://twitter.com/spiderfoot) [](https://discord.gg/vyvztrG) **SpiderFoot** is an open source intelligence (OSINT) automation tool. It integrates with just about every data source available and utilises a range of methods for data analysis, making that data easy to navigate. SpiderFoot has an embedded web-server for providing a clean and intuitive web-based interface but can also be used completely via the command-line. It's written in **Python 3** and **MIT-licensed**. ### FEATURES - Web based UI or CLI - Over 200 modules (see below) - Python 3.7+ - YAML-configurable [correlation engine](/correlations/README.md) with [37 pre-defined rules](/correlations) - CSV/JSON/GEXF export - API key export/import - SQLite back-end for custom querying - Highly configurable - Fully documented - Visualisations - TOR integration for dark web searching - Dockerfile for Docker-based deployments - Can call other tools like DNSTwist, Whatweb, Nmap and CMSeeK - [Actively developed since 2012!](https://medium.com/@micallst/lessons-learned-from-my-10-year-open-source-project-4a4c8c2b4f64) ### WANT MORE? Need more from SpiderFoot? Check out [SpiderFoot HX](https://www.spiderfoot.net/hx) for: - 100% Cloud-based and managed for you - Attack Surface Monitoring with change notifications by email, REST and Slack - Multiple targets per scan - Multi-user collaboration - Authenticated and 2FA - Investigations - Customer support - Third party tools pre-installed & configured - Drive it with a fully RESTful API - TOR integration built-in - Screenshotting - Bring your own Python SpiderFoot modules - Feed scan data to Splunk, ElasticSearch and REST endpoints See the full set of differences between SpiderFoot HX and the open source version [here](https://www.spiderfoot.net/open-source-vs-hx/). ### USES SpiderFoot can be used offensively (e.g. in a red team exercise or penetration test) for reconnaissance of your target or defensively to gather information about what you or your organisation might have exposed over the Internet. You can target the following entities in a SpiderFoot scan: - IP address - Domain/sub-domain name - Hostname - Network subnet (CIDR) - ASN - E-mail address - Phone number - Username - Person's name - Bitcoin address SpiderFoot's 200+ modules feed each other in a publisher/subscriber model to ensure maximum data extraction to do things like: - [Host/sub-domain/TLD enumeration/extraction](https://asciinema.org/a/295912) - [Email address, phone number and human name extraction](https://asciinema.org/a/295947) - [Bitcoin and Ethereum address extraction](https://asciinema.org/a/295957) - [Check for susceptibility to sub-domain hijacking](https://asciinema.org/a/344377) - DNS zone transfers - [Threat intelligence and Blacklist queries](https://asciinema.org/a/295949) - API integration with [SHODAN](https://asciinema.org/a/127601), [HaveIBeenPwned](https://asciinema.org/a/128731), [GreyNoise](https://asciinema.org/a/295943), AlienVault, SecurityTrails, etc. - [Social media account enumeration](https://asciinema.org/a/295923) - [S3/Azure/Digitalocean bucket enumeration/scraping](https://asciinema.org/a/295941) - IP geo-location - Web scraping, web content analysis - [Image, document and binary file meta data analysis](https://asciinema.org/a/296274) - Dark web searches - [Port scanning and banner grabbing](https://asciinema.org/a/295939) - [Data breach searches](https://asciinema.org/a/296145) - So much more... ### INSTALLING & RUNNING To install and run SpiderFoot, you need at least Python 3.7 and a number of Python libraries which you can install with `pip`. We recommend you install a packaged release since master will often have bleeding edge features and modules that aren't fully tested. #### Stable build (packaged release): ``` wget https://github.com/smicallef/spiderfoot/archive/v4.0.tar.gz tar zxvf v4.0.tar.gz cd spiderfoot-4.0 pip3 install -r requirements.txt python3 ./sf.py -l 127.0.0.1:5001 ``` #### Development build (cloning git master branch): ``` git clone https://github.com/smicallef/spiderfoot.git cd spiderfoot pip3 install -r requirements.txt python3 ./sf.py -l 127.0.0.1:5001 ``` Check out the [documentation](https://www.spiderfoot.net/documentation) and our [asciinema videos](https://asciinema.org/~spiderfoot) for more tutorials. ### COMMUNITY Whether you're a contributor, user or just curious about SpiderFoot and OSINT in general, we'd love to have you join our community! SpiderFoot now has a [Discord server](https://discord.gg/vyvztrG) for seeking help from the community, requesting features or just general OSINT chit-chat. ### WRITING CORRELATION RULES We have a comprehensive write-up and reference of the correlation rule-set introduced in SpiderFoot 4.0 [here](/correlations/README.md). Also take a look at the [template.yaml](/correlations/template.yaml) file for a walk through. The existing [37 rules](/correlations) are also quite readable and good as starting points for additional rules. ### MODULES / INTEGRATIONS SpiderFoot has over 200 modules, most of which *don't require API keys*, and many of those that do require API keys *have a free tier*. | Name | Description | Type | |:---------| :-----------|:-------| [AbstractAPI](https://app.abstractapi.com/)|Look up domain, phone and IP address information from AbstractAPI.|Tiered API [abuse.ch](https://www.abuse.ch)|Check if a host/domain, IP address or netblock is malicious according to Abuse.ch.|Free API [AbuseIPDB](https://www.abuseipdb.com)|Check if an IP address is malicious according to AbuseIPDB.com blacklist.|Tiered API [Abusix Mail Intelligence](https://abusix.org/)|Check if a netblock or IP address is in the Abusix Mail Intelligence blacklist.|Tiered API Account Finder|Look for possible associated accounts on over 500 social and other websites such as Instagram, Reddit, etc.|Internal [AdBlock Check](https://adblockplus.org/)|Check if linked pages would be blocked by AdBlock Plus.|Tiered API [AdGuard DNS](https://adguard.com/)|Check if a host would be blocked by AdGuard DNS.|Free API [Ahmia](https://ahmia.fi/)|Search Tor 'Ahmia' search engine for mentions of the target.|Free API [AlienVault IP Reputation](https://cybersecurity.att.com/)|Check if an IP or netblock is malicious according to the AlienVault IP Reputation database.|Free API [AlienVault OTX](https://otx.alienvault.com/)|Obtain information from AlienVault Open Threat Exchange (OTX)|Tiered API [Amazon S3 Bucket Finder](https://aws.amazon.com/s3/)|Search for potential Amazon S3 buckets associated with the target and attempt to list their contents.|Free API [Apple iTunes](https://itunes.apple.com/)|Search Apple iTunes for mobile apps.|Free API [Archive.org](https://archive.org/)|Identifies historic versions of interesting files/pages from the Wayback Machine.|Free API [ARIN](https://www.arin.net/)|Queries ARIN registry for contact information.|Free API [Azure Blob Finder](https://azure.microsoft.com/en-in/services/storage/blobs/)|Search for potential Azure blobs associated with the target and attempt to list their contents.|Free API Base64 Decoder|Identify Base64-encoded strings in URLs, often revealing interesting hidden information.|Internal [BGPView](https://bgpview.io/)|Obtain network information from BGPView API.|Free API Binary String Extractor|Attempt to identify strings in binary content.|Internal [BinaryEdge](https://www.binaryedge.io/)|Obtain information from BinaryEdge.io Internet scanning systems, including breaches, vulnerabilities, torrents and passive DNS.|Tiered API [Bing (Shared IPs)](https://www.bing.com/)|Search Bing for hosts sharing the same IP.|Tiered API [Bing](https://www.bing.com/)|Obtain information from bing to identify sub-domains and links.|Tiered API Bitcoin Finder|Identify bitcoin addresses in scraped webpages.|Internal [Bitcoin Who's Who](https://bitcoinwhoswho.com/)|Check for Bitcoin addresses against the Bitcoin Who's Who database of suspect/malicious addresses.|Tiered API [BitcoinAbuse](https://www.bitcoinabuse.com/)|Check Bitcoin addresses against the bitcoinabuse.com database of suspect/malicious addresses.|Free API [Blockchain](https://www.blockchain.com/)|Queries blockchain.info to find the balance of identified bitcoin wallet addresses.|Free API [blocklist.de](http://www.blocklist.de/en/index.html)|Check if a netblock or IP is malicious according to blocklist.de.|Free API [BotScout](https://botscout.com/)|Searches BotScout.com's database of spam-bot IP addresses and e-mail addresses.|Tiered API [botvrij.eu](https://botvrij.eu/)|Check if a domain is malicious according to botvrij.eu.|Free API [BuiltWith](https://builtwith.com/)|Query BuiltWith.com's Domain API for information about your target's web technology stack, e-mail addresses and more.|Tiered API [C99](https://api.c99.nl/)|Queries the C99 API which offers various data (geo location, proxy detection, phone lookup, etc).|Commercial API [CallerName](http://callername.com/)|Lookup US phone number location and reputation information.|Free API [Censys](https://censys.io/)|Obtain host information from Censys.io.|Tiered API [Certificate Transparency](https://crt.sh/)|Gather hostnames from historical certificates in crt.sh.|Free API [CertSpotter](https://sslmate.com/certspotter/)|Gather information about SSL certificates from SSLMate CertSpotter API.|Tiered API [CINS Army List](https://cinsscore.com/)|Check if a netblock or IP address is malicious according to Collective Intelligence Network Security (CINS) Army list.|Free API [CIRCL.LU](https://www.circl.lu/)|Obtain information from CIRCL.LU's Passive DNS and Passive SSL databases.|Free API [CleanBrowsing.org](https://cleanbrowsing.org/)|Check if a host would be blocked by CleanBrowsing.org DNS content filters.|Free API [CleanTalk Spam List](https://cleantalk.org)|Check if a netblock or IP address is on CleanTalk.org's spam IP list.|Free API [Clearbit](https://clearbit.com/)|Check for names, addresses, domains and more based on lookups of e-mail addresses on clearbit.com.|Tiered API [CloudFlare DNS](https://www.cloudflare.com/)|Check if a host would be blocked by CloudFlare DNS.|Free API [CoinBlocker Lists](https://zerodot1.gitlab.io/CoinBlockerListsWeb/)|Check if a domain appears on CoinBlocker lists.|Free API [CommonCrawl](http://commoncrawl.org/)|Searches for URLs found through CommonCrawl.org.|Free API [Comodo Secure DNS](https://www.comodo.com/secure-dns/)|Check if a host would be blocked by Comodo Secure DNS.|Tiered API Company Name Extractor|Identify company names in any obtained data.|Internal Cookie Extractor|Extract Cookies from HTTP headers.|Internal Country Name Extractor|Identify country names in any obtained data.|Internal Credit Card Number Extractor|Identify Credit Card Numbers in any data|Internal [Crobat API](https://sonar.omnisint.io/)|Search Crobat API for subdomains.|Free API Cross-Referencer|Identify whether other domains are associated ('Affiliates') of the target by looking for links back to the target site(s).|Internal [CRXcavator](https://crxcavator.io/)|Search CRXcavator for Chrome extensions.|Free API Custom Threat Feed|Check if a host/domain, netblock, ASN or IP is malicious according to your custom feed.|Internal [CyberCrime-Tracker.net](https://cybercrime-tracker.net/)|Check if a host/domain or IP address is malicious according to CyberCrime-Tracker.net.|Free API [Debounce](https://debounce.io/)|Check whether an email is disposable|Free API [Dehashed](https://www.dehashed.com/)|Gather breach data from Dehashed API.|Commercial API [Digital Ocean Space Finder](https://www.digitalocean.com/products/spaces/)|Search for potential Digital Ocean Spaces associated with the target and attempt to list their contents.|Free API DNS Brute-forcer|Attempts to identify hostnames through brute-forcing common names and iterations.|Internal DNS Common SRV|Attempts to identify hostnames through brute-forcing common DNS SRV records.|Internal [DNS for Family](https://dnsforfamily.com/)|Check if a host would be blocked by DNS for Family.|Free API DNS Look-aside|Attempt to reverse-resolve the IP addresses next to your target to see if they are related.|Internal DNS Raw Records|Retrieves raw DNS records such as MX, TXT and others.|Internal DNS Resolver|Resolves hosts and IP addresses identified, also extracted from raw content.|Internal DNS Zone Transfer|Attempts to perform a full DNS zone transfer.|Internal [DNSDB](https://www.farsightsecurity.com)|Query FarSight's DNSDB for historical and passive DNS data.|Tiered API [DNSDumpster](https://dnsdumpster.com/)|Passive subdomain enumeration using HackerTarget's DNSDumpster|Free API [DNSGrep](https://opendata.rapid7.com/)|Obtain Passive DNS information from Rapid7 Sonar Project using DNSGrep API.|Free API [DroneBL](https://dronebl.org/)|Query the DroneBL database for open relays, open proxies, vulnerable servers, etc.|Free API [DuckDuckGo](https://duckduckgo.com/)|Query DuckDuckGo's API for descriptive information about your target.|Free API E-Mail Address Extractor|Identify e-mail addresses in any obtained data.|Internal [EmailCrawlr](https://emailcrawlr.com/)|Search EmailCrawlr for email addresses and phone numbers associated with a domain.|Tiered API [EmailFormat](https://www.email-format.com/)|Look up e-mail addresses on email-format.com.|Free API [EmailRep](https://emailrep.io/)|Search EmailRep.io for email address reputation.|Tiered API [Emerging Threats](https://rules.emergingthreats.net/)|Check if a netblock or IP address is malicious according to EmergingThreats.net.|Free API Error String Extractor|Identify common error messages in content like SQL errors, etc.|Internal Ethereum Address Extractor|Identify ethereum addresses in scraped webpages.|Internal [Etherscan](https://etherscan.io)|Queries etherscan.io to find the balance of identified ethereum wallet addresses.|Free API File Metadata Extractor|Extracts meta data from documents and images.|Internal [Flickr](https://www.flickr.com/)|Search Flickr for domains, URLs and emails related to the specified domain.|Free API [Focsec](https://focsec.com/)|Look up IP address information from Focsec.|Tiered API [FortiGuard Antispam](https://www.fortiguard.com/)|Check if an IP address is malicious according to FortiGuard Antispam.|Free API [Fraudguard](https://fraudguard.io/)|Obtain threat information from Fraudguard.io|Tiered API [F-Secure Riddler.io](https://riddler.io/)|Obtain network information from F-Secure Riddler.io API.|Commercial API [FullContact](https://www.fullcontact.com)|Gather domain and e-mail information from FullContact.com API.|Tiered API [FullHunt](https://fullhunt.io/)|Identify domain attack surface using FullHunt API.|Tiered API [Github](https://github.com/)|Identify associated public code repositories on Github.|Free API [GLEIF](https://search.gleif.org/)|Look up company information from Global Legal Entity Identifier Foundation (GLEIF).|Tiered API [Google Maps](https://cloud.google.com/maps-platform/)|Identifies potential physical addresses and latitude/longitude coordinates.|Tiered API [Google Object Storage Finder](https://cloud.google.com/storage)|Search for potential Google Object Storage buckets associated with the target and attempt to list their contents.|Free API [Google SafeBrowsing](https://developers.google.com/safe-browsing/v4/lookup-api)|Check if the URL is included on any of the Safe Browsing lists.|Free API [Google](https://developers.google.com/custom-search)|Obtain information from the Google Custom Search API to identify sub-domains and links.|Tiered API [Gravatar](https://secure.gravatar.com/)|Retrieve user information from Gravatar API.|Free API [Grayhat Warfare](https://buckets.grayhatwarfare.com/)|Find bucket names matching the keyword extracted from a domain from Grayhat API.|Tiered API [Greensnow](https://greensnow.co/)|Check if a netblock or IP address is malicious according to greensnow.co.|Free API [grep.app](https://grep.app/)|Search grep.app API for links and emails related to the specified domain.|Free API [GreyNoise Community](https://greynoise.io/)|Obtain IP enrichment data from GreyNoise Community API|Tiered API [GreyNoise](https://greynoise.io/)|Obtain IP enrichment data from GreyNoise|Tiered API [HackerOne (Unofficial)](http://www.nobbd.de/)|Check external vulnerability scanning/reporting service h1.nobbd.de to see if the target is listed.|Free API [HackerTarget](https://hackertarget.com/)|Search HackerTarget.com for hosts sharing the same IP.|Free API Hash Extractor|Identify MD5 and SHA hashes in web content, files and more.|Internal [HaveIBeenPwned](https://haveibeenpwned.com/)|Check HaveIBeenPwned.com for hacked e-mail addresses identified in breaches.|Commercial API Hosting Provider Identifier|Find out if any IP addresses identified fall within known 3rd party hosting ranges, e.g. Amazon, Azure, etc.|Internal [Host.io](https://host.io)|Obtain information about domain names from host.io.|Tiered API Human Name Extractor|Attempt to identify human names in fetched content.|Internal [Hunter.io](https://hunter.io/)|Check for e-mail addresses and names on hunter.io.|Tiered API [Hybrid Analysis](https://www.hybrid-analysis.com)|Search Hybrid Analysis for domains and URLs related to the target.|Free API IBAN Number Extractor|Identify International Bank Account Numbers (IBANs) in any data.|Internal [Iknowwhatyoudownload.com](https://iknowwhatyoudownload.com/en/peer/)|Check iknowwhatyoudownload.com for IP addresses that have been using torrents.|Tiered API [IntelligenceX](https://intelx.io/)|Obtain information from IntelligenceX about identified IP addresses, domains, e-mail addresses and phone numbers.|Tiered API Interesting File Finder|Identifies potential files of interest, e.g. office documents, zip files.|Internal [Internet Storm Center](https://isc.sans.edu)|Check if an IP address is malicious according to SANS ISC.|Free API [ipapi.co](https://ipapi.co/)|Queries ipapi.co to identify geolocation of IP Addresses using ipapi.co API|Tiered API [ipapi.com](https://ipapi.com/)|Queries ipapi.com to identify geolocation of IP Addresses using ipapi.com API|Tiered API [IPInfo.io](https://ipinfo.io)|Identifies the physical location of IP addresses identified using ipinfo.io.|Tiered API [IPQualityScore](https://www.ipqualityscore.com/)|Determine if target is malicious using IPQualityScore API|Tiered API [ipregistry](https://ipregistry.co/)|Query the ipregistry.co database for reputation and geo-location.|Tiered API [ipstack](https://ipstack.com/)|Identifies the physical location of IP addresses identified using ipstack.com.|Tiered API [JsonWHOIS.com](https://jsonwhois.com)|Search JsonWHOIS.com for WHOIS records associated with a domain.|Tiered API Junk File Finder|Looks for old/temporary and other similar files.|Internal [Keybase](https://keybase.io/)|Obtain additional information about domain names and identified usernames.|Free API [Koodous](https://koodous.com/apks/)|Search Koodous for mobile apps.|Tiered API [LeakIX](https://leakix.net/)|Search LeakIX for host data leaks, open ports, software and geoip.|Free API [Leak-Lookup](https://leak-lookup.com/)|Searches Leak-Lookup.com's database of breaches.|Free API [Maltiverse](https://maltiverse.com)|Obtain information about any malicious activities involving IP addresses|Free API [MalwarePatrol](https://www.malwarepatrol.net/)|Searches malwarepatrol.net's database of malicious URLs/IPs.|Tiered API [MetaDefender](https://metadefender.opswat.com/)|Search MetaDefender API for IP address and domain IP reputation.|Tiered API [Mnemonic PassiveDNS](https://www.mnemonic.no)|Obtain Passive DNS information from PassiveDNS.mnemonic.no.|Free API [multiproxy.org Open Proxies](https://multiproxy.org/)|Check if an IP address is an open proxy according to multiproxy.org open proxy list.|Free API [MySpace](https://myspace.com/)|Gather username and location from MySpace.com profiles.|Free API [NameAPI](https://www.nameapi.org/)|Check whether an email is disposable|Tiered API [NetworksDB](https://networksdb.io/)|Search NetworksDB.io API for IP address and domain information.|Tiered API [NeutrinoAPI](https://www.neutrinoapi.com/)|Search NeutrinoAPI for phone location information, IP address information, and host reputation.|Tiered API [numverify](http://numverify.com/)|Lookup phone number location and carrier information from numverify.com.|Tiered API [Onion.link](https://onion.link/)|Search Tor 'Onion City' search engine for mentions of the target domain using Google Custom Search.|Free API [Onionsearchengine.com](https://as.onionsearchengine.com)|Search Tor onionsearchengine.com for mentions of the target domain.|Free API [Onyphe](https://www.onyphe.io)|Check Onyphe data (threat list, geo-location, pastries, vulnerabilities) about a given IP.|Tiered API [Open Bug Bounty](https://www.openbugbounty.org/)|Check external vulnerability scanning/reporting service openbugbounty.org to see if the target is listed.|Free API [OpenCorporates](https://opencorporates.com)|Look up company information from OpenCorporates.|Tiered API [OpenDNS](https://www.opendns.com/)|Check if a host would be blocked by OpenDNS.|Free API [OpenNIC DNS](https://www.opennic.org/)|Resolves host names in the OpenNIC alternative DNS system.|Free API [OpenPhish](https://openphish.com/)|Check if a host/domain is malicious according to OpenPhish.com.|Free API [OpenStreetMap](https://www.openstreetmap.org/)|Retrieves latitude/longitude coordinates for physical addresses from OpenStreetMap API.|Free API Page Information|Obtain information about web pages (do they take passwords, do they contain forms, etc.)|Internal [PasteBin](https://pastebin.com/)|PasteBin search (via Google Search API) to identify related content.|Tiered API PGP Key Servers|Look up domains and e-mail addresses in PGP public key servers.|Internal [PhishStats](https://phishstats.info/)|Check if a netblock or IP address is malicious according to PhishStats.|Free API [PhishTank](https://phishtank.com/)|Check if a host/domain is malicious according to PhishTank.|Free API Phone Number Extractor|Identify phone numbers in scraped webpages.|Internal Port Scanner - TCP|Scans for commonly open TCP ports on Internet-facing systems.|Internal [Project Honey Pot](https://www.projecthoneypot.org/)|Query the Project Honey Pot database for IP addresses.|Free API [ProjectDiscovery Chaos](https://chaos.projectdiscovery.io)|Search for hosts/subdomains using chaos.projectdiscovery.io|Commercial API [Psbdmp](https://psbdmp.cc/)|Check psbdmp.cc (PasteBin Dump) for potentially hacked e-mails and domains.|Free API [Pulsedive](https://pulsedive.com/)|Obtain information from Pulsedive's API.|Tiered API [PunkSpider](https://punkspider.io/)|Check the QOMPLX punkspider.io service to see if the target is listed as vulnerable.|Free API [Quad9](https://quad9.net/)|Check if a host would be blocked by Quad9 DNS.|Free API [ReverseWhois](https://www.reversewhois.io/)|Reverse Whois lookups using reversewhois.io.|Free API [RIPE](https://www.ripe.net/)|Queries the RIPE registry (includes ARIN data) to identify netblocks and other info.|Free API [RiskIQ](https://community.riskiq.com/)|Obtain information from RiskIQ's (formerly PassiveTotal) Passive DNS and Passive SSL databases.|Tiered API [Robtex](https://www.robtex.com/)|Search Robtex.com for hosts sharing the same IP.|Free API [searchcode](https://searchcode.com/)|Search searchcode for code repositories mentioning the target domain.|Free API [SecurityTrails](https://securitytrails.com/)|Obtain Passive DNS and other information from SecurityTrails|Tiered API [Seon](https://seon.io/)|Queries seon.io to gather intelligence about IP Addresses, email addresses, and phone numbers|Commercial API [SHODAN](https://www.shodan.io/)|Obtain information from SHODAN about identified IP addresses.|Tiered API Similar Domain Finder|Search various sources to identify similar looking domain names, for instance squatted domains.|Internal [Skymem](http://www.skymem.info/)|Look up e-mail addresses on Skymem.|Free API [SlideShare](https://www.slideshare.net)|Gather name and location from SlideShare profiles.|Free API [Snov](https://snov.io/)|Gather available email IDs from identified domains|Tiered API [Social Links](https://sociallinks.io/)|Queries SocialLinks.io to gather intelligence from social media platforms and dark web.|Commercial API [Social Media Profile Finder](https://developers.google.com/custom-search)|Tries to discover the social media profiles for human names identified.|Tiered API Social Network Identifier|Identify presence on social media networks such as LinkedIn, Twitter and others.|Internal [SORBS](http://www.sorbs.net/)|Query the SORBS database for open relays, open proxies, vulnerable servers, etc.|Free API [SpamCop](https://www.spamcop.net/)|Check if a netblock or IP address is in the SpamCop database.|Free API [Spamhaus Zen](https://www.spamhaus.org/)|Check if a netblock or IP address is in the Spamhaus Zen database.|Free API [spur.us](https://spur.us/)|Obtain information about any malicious activities involving IP addresses found|Commercial API [SpyOnWeb](http://spyonweb.com/)|Search SpyOnWeb for hosts sharing the same IP address, Google Analytics code, or Google Adsense code.|Tiered API SSL Certificate Analyzer|Gather information about SSL certificates used by the target's HTTPS sites.|Internal [StackOverflow](https://www.stackexchange.com)|Search StackOverflow for any mentions of a target domain. Returns potentially related information.|Tiered API [Steven Black Hosts](https://github.com/StevenBlack/hosts)|Check if a domain is malicious (malware or adware) according to Steven Black Hosts list.|Free API Strange Header Identifier|Obtain non-standard HTTP headers returned by web servers.|Internal Subdomain Takeover Checker|Check if affiliated subdomains are vulnerable to takeover.|Internal [Sublist3r PassiveDNS](https://api.sublist3r.com)|Passive subdomain enumeration using Sublist3r's API|Free API [SURBL](http://www.surbl.org/)|Check if a netblock, IP address or domain is in the SURBL blacklist.|Free API [Talos Intelligence](https://talosintelligence.com/)|Check if a netblock or IP address is malicious according to TalosIntelligence.|Free API [TextMagic](https://www.textmagic.com/)|Obtain phone number type from TextMagic API|Tiered API [Threat Jammer](https://threatjammer.com)|Check if an IP address is malicious according to ThreatJammer.com|Tiered API [ThreatCrowd](https://www.threatcrowd.org)|Obtain information from ThreatCrowd about identified IP addresses, domains and e-mail addresses.|Free API [ThreatFox](https://threatfox.abuse.ch)|Check if an IP address is malicious according to ThreatFox.|Free API [ThreatMiner](https://www.threatminer.org/)|Obtain information from ThreatMiner's database for passive DNS and threat intelligence.|Free API TLD Searcher|Search all Internet TLDs for domains with the same name as the target (this can be very slow.)|Internal [Tool - CMSeeK]([https://github.com/Tuhinshubhra/CMSeeK](https://github.com/Tuhinshubhra/CMSeeK))|Identify what Content Management System (CMS) might be used.|Tool [Tool - DNSTwist]([https://github.com/elceef/dnstwist](https://github.com/elceef/dnstwist))|Identify bit-squatting, typo and other similar domains to the target using a local DNSTwist installation.|Tool [Tool - nbtscan]([http://www.unixwiz.net/tools/nbtscan.html](http://www.unixwiz.net/tools/nbtscan.html))|Scans for open NETBIOS nameservers on your target's network.|Tool [Tool - Nmap]([https://nmap.org/](https://nmap.org/))|Identify what Operating System might be used.|Tool [Tool - Nuclei]([https://nuclei.projectdiscovery.io/](https://nuclei.projectdiscovery.io/))|Fast and customisable vulnerability scanner.|Tool [Tool - onesixtyone]([https://github.com/trailofbits/onesixtyone](https://github.com/trailofbits/onesixtyone))|Fast scanner to find publicly exposed SNMP services.|Tool [Tool - Retire.js]([http://retirejs.github.io/retire.js/](http://retirejs.github.io/retire.js/))|Scanner detecting the use of JavaScript libraries with known vulnerabilities|Tool [Tool - snallygaster]([https://github.com/hannob/snallygaster](https://github.com/hannob/snallygaster))|Finds file leaks and other security problems on HTTP servers.|Tool [Tool - testssl.sh]([https://testssl.sh](https://testssl.sh))|Identify various TLS/SSL weaknesses, including Heartbleed, CRIME and ROBOT.|Tool [Tool - TruffleHog]([https://github.com/trufflesecurity/truffleHog](https://github.com/trufflesecurity/truffleHog))|Searches through git repositories for high entropy strings and secrets, digging deep into commit history.|Tool [Tool - WAFW00F]([https://github.com/EnableSecurity/wafw00f](https://github.com/EnableSecurity/wafw00f))|Identify what web application firewall (WAF) is in use on the specified website.|Tool [Tool - Wappalyzer]([https://www.wappalyzer.com/](https://www.wappalyzer.com/))|Wappalyzer indentifies technologies on websites.|Tool [Tool - WhatWeb]([https://github.com/urbanadventurer/whatweb](https://github.com/urbanadventurer/whatweb))|Identify what software is in use on the specified website.|Tool [TOR Exit Nodes](https://metrics.torproject.org/)|Check if an IP adddress or netblock appears on the Tor Metrics exit node list.|Free API [TORCH](https://torchsearch.wordpress.com/)|Search Tor 'TORCH' search engine for mentions of the target domain.|Free API [Trashpanda](https://got-hacked.wtf)|Queries Trashpanda to gather intelligence about mentions of target in pastesites|Tiered API [Trumail](https://trumail.io/)|Check whether an email is disposable|Free API [Twilio](https://www.twilio.com/)|Obtain information from Twilio about phone numbers. Ensure you have the Caller Name add-on installed in Twilio.|Tiered API [Twitter](https://twitter.com/)|Gather name and location from Twitter profiles.|Free API [UCEPROTECT](http://www.uceprotect.net/)|Check if a netblock or IP address is in the UCEPROTECT database.|Free API [URLScan.io](https://urlscan.io/)|Search URLScan.io cache for domain information.|Free API [Venmo](https://venmo.com/)|Gather user information from Venmo API.|Free API [ViewDNS.info](https://viewdns.info/)|Identify co-hosted websites and perform reverse Whois lookups using ViewDNS.info.|Tiered API [VirusTotal](https://www.virustotal.com/)|Obtain information from VirusTotal about identified IP addresses.|Tiered API [VoIP Blacklist (VoIPBL)](https://voipbl.org/)|Check if an IP address or netblock is malicious according to VoIP Blacklist (VoIPBL).|Free API [VXVault.net](http://vxvault.net/)|Check if a domain or IP address is malicious according to VXVault.net.|Free API Web Analytics Extractor|Identify web analytics IDs in scraped webpages and DNS TXT records.|Internal Web Framework Identifier|Identify the usage of popular web frameworks like jQuery, YUI and others.|Internal Web Server Identifier|Obtain web server banners to identify versions of web servers being used.|Internal Web Spider|Spidering of web-pages to extract content for searching.|Internal [WhatCMS](https://whatcms.org/)|Check web technology using WhatCMS.org API.|Tiered API [Whoisology](https://whoisology.com/)|Reverse Whois lookups using Whoisology.com.|Commercial API Whois|Perform a WHOIS look-up on domain names and owned netblocks.|Internal [Whoxy](https://www.whoxy.com/)|Reverse Whois lookups using Whoxy.com.|Commercial API [WiGLE](https://wigle.net/)|Query WiGLE to identify nearby WiFi access points.|Free API [Wikileaks](https://wikileaks.org/)|Search Wikileaks for mentions of domain names and e-mail addresses.|Free API [Wikipedia Edits](https://www.wikipedia.org/)|Identify edits to Wikipedia articles made from a given IP address or username.|Free API [XForce Exchange](https://exchange.xforce.ibmcloud.com/)|Obtain IP reputation and passive DNS information from IBM X-Force Exchange.|Tiered API [Yandex DNS](https://yandex.com/)|Check if a host would be blocked by Yandex DNS.|Free API [Zetalytics](https://zetalytics.com/)|Query the Zetalytics database for hosts on your target domain(s).|Tiered API [ZoneFile.io](https://zonefiles.io)|Search ZoneFiles.io Domain query API for domain information.|Tiered API [Zone-H Defacement Check](https://zone-h.org/)|Check if a hostname/domain appears on the zone-h.org 'special defacements' RSS feed.|Free API ### DOCUMENTATION Read more at the [project website](https://www.spiderfoot.net/r.php?u=aHR0cHM6Ly93d3cuc3BpZGVyZm9vdC5uZXQv&s=os_gh), including more complete documentation, blog posts with tutorials/guides, plus information about [SpiderFoot HX](https://www.spiderfoot.net/r.php?u=aHR0cHM6Ly93d3cuc3BpZGVyZm9vdC5uZXQvaHgvCg==&s=os_gh). Latest updates announced on [Twitter](https://twitter.com/spiderfoot). --- ## File: correlations/README.md ## Background SpiderFoot’s goal is to automate OSINT collection and analysis to the greatest extent possible. Since its inception, SpiderFoot has heavily focused on automating OSINT collection and entity extraction, but the automation of common analysis tasks -- beyond some reporting and visualisations -- has been left entirely to the user. The meant that the strength of SpiderFoot's data collection capabilities has sometimes been its weakness since with so much data collected, users have often needed to export it and use other tools to weed out data of interest. ## Introducing Correlations We started tackling this analysis gap with the launch of SpiderFoot HX in 2019 through the introduction of the "Correlations" feature. This feature was represented by some 30 "correlation rules" that ran with each scan, analyzing data and presenting results reflecting SpiderFoot's opinionated view on what may be important or interesting. Here are a few of those rules as examples: * Hosts/IPs reported as malicious by multiple data sources * Outlier web servers (can be an indication of shadow IT) * Databases exposed on the Internet * Open ports revealing software versions * and many more. With the release of SpiderFoot 4.0 we wanted to bring this capability from SpiderFoot HX to the community, but also re-imagine it at the same time so that the community might not simply run rules we provide, but also write their own correlation rules and contribute them back. We also hope that just as with modules, we see a long list of contributions made in the years ahead so that all may benefit. With that said, let's get into what these rules look like and how to write one. ## Key concepts ### YAML The rules themselves are written in YAML. Why YAML? It’s easy to read, write, allows for comments and is increasingly commonplace in many modern tools. ### Rule structure The simplest way to think of a SpiderFoot correlation rule is like a simple database query that consists of a few sections: 1. Defining the rule itself (`id`, `version` and `meta` sections). 2. Stating what you'd like to extract from the scan results (`collections` section). 3. Grouping that data in some way (`aggregation` section; optional). 3. Performing some analysis over that data in some way (`analysis` section; optional). 4. Presenting the results (`headline` section). ### Example rule Here's an example rule that looks at SpiderFoot scan results for data revealing open TCP ports where the banner (the data returned upon connecting to the port) reports a software version. It does so by applying some regular expressions to the content of `TCP_PORT_OPEN_BANNER` data elements, filtering out some false positives and then grouping the results by the banner itself so that one correlation result is created per banner revealing a version: ```yaml id: open_port_version version: 1 meta: name: Open TCP port reveals version A possible software version has been revealed on an open port. Such information may reveal the use of old/unpatched software used by the target. risk: INFO collections: - collect: - method: exact field: type value: TCP_PORT_OPEN_BANNER - method: regex field: data value: .*[0-9]\.[0-9].* - method: regex field: data value: not .*Mime-Version.* - method: regex field: data value: not .*HTTP/1.* aggregation: field: data headline: "Software version revealed on open port: {data}" ``` ### The outcome To show this in practice, we can run a simple scan against a target, in this case focusing on performing a port scan: ``` -> # python3.9 ./sf.py -s www.binarypool.com -m sfp_dnsresolve,sfp_portscan_tcp 2022-04-06 08:14:58,476 [INFO] sflib : Scan [94EB5F0B] for 'www.binarypool.com' initiated. ... sfp_portscan_tcp Open TCP Port Banner SSH-2.0-OpenSSH_7.2p2 Ubuntu-4ubuntu2.10 ... 2022-04-06 08:15:23,110 [INFO] correlation : New correlation [open_port_version]: Software version revealed on open port: SSH-2.0-OpenSSH_7.2p2 Ubuntu-4ubuntu2.10 2022-04-06 08:15:23,244 [INFO] sflib : Scan [94EB5F0B] completed. ``` We can see above that a port was found to be open by the `sfp_portscan_tcp` module, and it happens to include a version. The correlation rule `open_port_version` picked this up and reported it. This is also visible in the web interface: **NOTE:** Rules will only succeed if relevant data exists in your scan results in the first place. In other words, correlation rules analyze scan data, they don't collect data from targets. ### How it works In short, SpiderFoot translates the YAML rules into a combination queries against the backend database of scan results and Python logic to filter and group the results, creating "correlation results" in the SpiderFoot database. These results can be viewed in the SpiderFot web interface or from the SpiderFoot CLI. You can also query them directly out of the SQLite database if you like (they are in the `tbl_scan_correlation_results` table, and the `tbl_scan_correlation_results_events` table maps the events (data elements) to the correlation result). ### The rules Each rule exists as a YAML file within the `/correlations` folder in the SpiderFoot installation path. Here you can see a list of rules in 4.0, which we hope to grow over time: ```sh cert_expired.yaml host_only_from_certificatetransparency.yaml outlier_ipaddress.yaml cloud_bucket_open.yaml http_errors.yaml outlier_registrar.yaml cloud_bucket_open_related.yaml human_name_in_whois.yaml outlier_webserver.yaml data_from_base64.yaml internal_host.yaml remote_desktop_exposed.yaml data_from_docmeta.yaml multiple_malicious.yaml root_path_needs_auth.yaml database_exposed.yaml multiple_malicious_affiliate.yaml stale_host.yaml dev_or_test_system.yaml multiple_malicious_cohost.yaml strong_affiliate_certs.yaml dns_zone_transfer_possible.yaml name_only_from_pasteleak_site.yaml strong_similardomain_crossref.yaml egress_ip_from_wikipedia.yaml open_port_version.yaml template.yaml email_in_multiple_breaches.yaml outlier_cloud.yaml vulnerability_critical.yaml email_in_whois.yaml outlier_country.yaml vulnerability_high.yaml email_only_from_pasteleak_site.yaml outlier_email.yaml vulnerability_mediumlow.yaml host_only_from_bruteforce.yaml outlier_hostname.yaml ``` ### Rule components The rules themselves are broken down into the following components: **Meta**: Describes the rule itself so that humans understand what the rule does and the risk level of any results. This information is used mostly in the web interface and CLI. **Collections**: A collection represents a set of data pulled from scan results, to be used in later aggregation and analysis stages. Each rule can have multiple collections. **Aggregations**: An aggregation buckets the collected data into groups for analysis in distinct groups of data elements. **Analysis**: Analysis performs (you guessed it) analysis on the data to whittle down the data elements to what ultimately gets reported. For example, the analysis stage may look only for cases where the data field is repeated in the data set, indicating it was found multiple times and therefore discarding any only appearing once. **Headline**: The headline represents the actual correlation title that summarizes what was found. You can think of this as equivalent to a meal name (beef stew), and all the data elements as being the ingredients (beef, tomatoes, onions, etc.). ### Creating a rule To create your own rule, simply copy the `template.yaml` file in the `correlations` folder to a meaningful name that matches the ID you intend to provide it, e.g. `aws_cloud_usage.yaml` and edit the rule to fit your needs. Save it and re-start SpiderFoot for the rule to be loaded. If there are any syntax errors, SpiderFoot will abort at startup and (hopefully) give you enough information to know where the error is. The `template.yaml` file is also a good next point of reference to better understand the structure of the rules and how to use them. We also recommend taking a look through the actual rules themselves to see the concepts in practice. ## Rule Reference **id**: The internal ID for this rule, which needs to match the filename. **version**: The rule syntax version. This must be `1` for now. **meta**: This section contains a few important fields used to describe the rule. * **name**: A short, human readable name for the rule. * **description**: A longer (can be multi-paragraph) description of the rule. * **risk**: The risk level represented by this rule's findings. Can be `INFO`, `LOW`, `MEDIUM`, `HIGH`. **collection**: A correlation rule contains one or more `collect` blocks. Each `collect` block contains one or more `method` blocks telling SpiderFoot what criteria to use for extracting data from the database and how to filter it down. * **collect**: Technically, the first `method` block in each `collect` block is what actually pulls data from the database, and each subsequent `method` refines that dataset down to what you’re seeking. You may have multiple `collect` blocks overall but the rule remains that within each `collect`, the first `method` pulls data from the database and subsequent `method` blocks within the `collect` refine that data. * **method**: Each `method` block tells SpiderFoot how to collect and refine data. Each `collect` must contain at least one `method` block. Valid methods are `exact` for performing an exact match of the chosen `field` to the supplied `value`, or `regex` to perform regular expression matching. * **field**: Each `method` block has a `field` upon which the matching should be performed. Valid fields are `type` (e.g. `INTERNET_NAME`), `module` (e.g. `sfp_whois`) and `data`, which would be the value of the data element (e.g. in case of an `INTERNET_NAME`, the `data` would be the hostname). After the first `method` block, you can also prefix the field with `source.`, `child.` or `entity.` to refer to the fields of the source, children or relevant entities of the collected data, respectively (see `multiple_malicious.yaml` and `data_from_docmeta.yaml` as examples of this approach). * **value**: Here you supply the value or values you wish to match against the field you supplied in `field`. If your `method` was `regex`, this would be a regular expression. **aggregation**: With all the data elements in their collections, you can now aggregate them into buckets for further analysis or immediately generate results from the rule. While the collection phase is about obtaining the data from the database and filtering down to data of interest, the aggregation phase is about grouping that data in different ways in order to support analysis and/or grouping reported results. Aggregation simply iterates through the data elements in each collection and places them into groups based on the `field` specified. For instance if you pick the `type` field, you’ll end up with data elements with the same `type` field grouped together. The purpose of this grouping is two-fold: to support the analysis stage, or if you don’t have the analysis stage, it’s how your correlation results will be grouped for the user. * **field**: The `field` defines how you'd like your data elements grouped together. Just like the `field` option in `method` blocks above, you may prefix the field with `source.`, `child.` or `entity.` to apply the aggregation on those fields of the data element instead. For example, if you intended to look for multiple occurrences of a hostname, you would specify `data` here as that field, since you want to count the number of times the value of the `data` field appears. **analysis** The analysis section applies (you guessed it) some analysis to the aggregated results or collections directly if you didn’t perform any aggregation, and drops candidate results if they fail this stage. Various analysis `method` types exist, and each takes different options, described below. * **method**: * **threshold**: Drop any collection/aggregation of data elements that do not meet the defined thresholds. You would use this analysis rule when wanting to generate a result only when a data element has appeared more or less than a limit specified, for instance reporting when an email address is reported just once, or more than 100 times. * **field**: The field you want to apply the threshold too. As per above, you can use `child.`, `source.` and `entity.` field prefixes here too. * **count_unique_only**: By default the threshold is applied to the `field` specified on all data elements, but by setting `count_unique_only` to `true`, you can limit the threshold to only unique values in the `field` specified, so as not to also count duplicates. * **minimum**: The minimum number of data elements that must appear within the collection or aggregation. * **maximum**: The maximum number of data elements that must appear within the collection or aggregation. * **outlier**: Only keep outliers within any collection/aggregation of data elements. * **maximum_percent**: The maximum percentage of the overall results that an aggregation can represent. This method requires that you have performed an aggregation on a certain field in order to function. For example, if you aggregate on the `data` field of your collections, and one of those buckets contains less than 10% of the overall volume, it will be reported as an outlier. * **noisy_percent**: By default this is `10`, meaning that if the average percentage every bucket is below 10%, don't report outliers since the dataset is anomalous. * **first_collection_only**: Only keep data elements that appeared in the first collection but not any others. For example, this is handy for finding cases where data was found from one or several data sources but not others. * **field**: The field you want to use for looking up between collections. * **match_all_to_first_collection**: Only keep data elements that have matched in some way to the first collection. This requires an aggregation to have been performed, as the field used for aggregation is what will be used for checking for a match. * **match_method**: How to match between all collections and the first collection. Options are `contains` (simple wildcard match), `exact` and `subnet` which reports a match if the expected field may contain an IP address that is within the first collection field containing a subnet. **headline** After all data elements have been collected, filtered down, aggregated and analyzed, if data elements are remaining, these are what we call "correlation results" -> the results of your correlation rule. These need a "headline" to summarize the findings, which you can define here. To place any value from your data into the headline, you must enclose the field in `{}`, e.g. `{entity.data}`. There are two ways to write a `headline` rule. The typical way is to simply have `headline: titletexthere`, or have it as a block, in which case you can be more granular about how the correlation results are published: * **text**: The headline text, as described above. * **publish_collections**: The collection you wish to have associated with the correlation result. This is not often needed, but more in combination with the `match_all_to_first_collection` analysis rule in case your first collection is only used as a reference point and not actually contain any data elements you wish to publish with this correlation result. Take a look at the `egress_ip_from_wikipedia.yaml` rule for an example of this used in practice. ### A note about `child.`, `source.` and `entity.` field prefixes Every data element pulled in the first `match` rule in a collection will also have any children (data resulting from that data element), the source (the data element that this data element was generated from) and entity (the source, or source of source, etc. that was an entity like IP address, domain, etc.). This enables you to prefix subsequent (and only subsequent!) match block field names with `child.`, `source.` and `entity.` if you wish to match based on those fields. These prefixes, as shown above, can also be used in the `aggregation`, `analysis` and `headline` sections too. It is vital to note that these prefixes **always** are in reference to the first `match` block within each `collect` block, since every subsequent `match` block is always a refinement of the first `match` block. This can be complicated, so let's use an example to illustrate. Let's say your scan has found a hostname (a data element type of `INTERNET_NAME`) of `foo`, and it found that within some webpage content (a data element type of `TARGET_WEB_CONTENT`) of "This is some web content: foo", which was from a URL (data element type of `LINKED_URL_INTERNAL`) of "https://bar/page.html", which was from another host named `bar`. Here's the data discovery path: `bar` [`INTERNET_NAME`] -> `https://bar/page.html` [`LINKED_URL_INTERNAL`] -> `This is some web content: foo` [`TARGET_WEB_CONTENT`] -> `foo` [`INTERNET_NAME`] If we were to look at `This is some web content: foo` in our rule, here are the `data` and `type` fields you would expect to exist (`module` would also exist but has been left out of this example for brevity): * `data`: `This is some web content: foo` * `type`: `TARGET_WEB_CONTENT` * `source.data`: `https://bar/page.html` * `source.type`: `LINKED_URL_INTERNAL` * `child.data`: `foo` * `child.type`: `INTERNET_NAME` * `entity.type`: `INTERNET_NAME` * `entity.data`: `bar` Notice how the `entity.type` and `entity.data` fields for "This is some web content: foo" is **not** the `LINKED_URL_INTERNAL` data element, but actually the `bar` `INTERNET_NAME` data element. This is because an `INTERNET_NAME` is an entity, but a `LINKED_URL_INTERNAL` is not. You can look in `spiderfoot/db.py` to see which data types are entities and which are not. --- ## File: docs/index.rst .. spiderfoot documentation master file, created by sphinx-quickstart on Sat Jun 26 01:55:34 2021. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to spiderfoot's documentation! ====================================== .. toctree:: :maxdepth: 4 :caption: Contents: spiderfoot Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` --- ## File: docs/spiderfoot.rst spiderfoot package ================== Submodules ---------- spiderfoot.db module -------------------- .. automodule:: spiderfoot.db :members: :undoc-members: :show-inheritance: spiderfoot.event module ----------------------- .. automodule:: spiderfoot.event :members: :undoc-members: :show-inheritance: spiderfoot.helpers module ------------------------- .. automodule:: spiderfoot.helpers :members: :undoc-members: :show-inheritance: spiderfoot.plugin module ------------------------ .. automodule:: spiderfoot.plugin :members: :undoc-members: :show-inheritance: spiderfoot.target module ------------------------ .. automodule:: spiderfoot.target :members: :undoc-members: :show-inheritance: Module contents --------------- .. automodule:: spiderfoot :members: :undoc-members: :show-inheritance: