README.md 9.87 KB
Newer Older
Sophie Brun's avatar
Sophie Brun committed
1
<p align="center">
Sophie Brun's avatar
Sophie Brun committed
2
  <a href="https://wpscan.com/">
Sophie Brun's avatar
Sophie Brun committed
3
4
5
6
7
8
9
    <img src="https://raw.githubusercontent.com/wpscanteam/wpscan/gh-pages/images/wpscan_logo.png" alt="WPScan logo">
  </a>
</p>

<h3 align="center">WPScan</h3>

<p align="center">
Sophie Brun's avatar
Sophie Brun committed
10
  WordPress Security Scanner
Sophie Brun's avatar
Sophie Brun committed
11
12
  <br>
  <br>
Sophie Brun's avatar
Sophie Brun committed
13
  <a href="https://wpscan.com/" title="homepage" target="_blank">WPScan WordPress Vulnerability Database</a> - <a href="https://wordpress.org/plugins/wpscan/" title="wordpress security plugin" target="_blank">WordPress Security Plugin</a>
Sophie Brun's avatar
Sophie Brun committed
14
15
16
17
</p>

<p align="center">
  <a href="https://badge.fury.io/rb/wpscan" target="_blank"><img src="https://badge.fury.io/rb/wpscan.svg"></a>
Sophie Brun's avatar
Sophie Brun committed
18
  <a href="https://hub.docker.com/r/wpscanteam/wpscan/" target="_blank"><img src="https://img.shields.io/docker/pulls/wpscanteam/wpscan.svg"></a>
Sophie Brun's avatar
Sophie Brun committed
19
  <a href="https://github.com/wpscanteam/wpscan/actions?query=workflow%3ABuild" target="_blank"><img src="https://github.com/wpscanteam/wpscan/workflows/Build/badge.svg"></a>
Sophie Brun's avatar
Sophie Brun committed
20
21
  <a href="https://codeclimate.com/github/wpscanteam/wpscan" target="_blank"><img src="https://codeclimate.com/github/wpscanteam/wpscan/badges/gpa.svg"></a>
</p>
Sophie Brun's avatar
Sophie Brun committed
22

Sophie Brun's avatar
Sophie Brun committed
23
24
# INSTALL

Sophie Brun's avatar
Sophie Brun committed
25
## Prerequisites
Sophie Brun's avatar
Sophie Brun committed
26

Sophie Brun's avatar
Sophie Brun committed
27
- (Optional but highly recommended: [RVM](https://rvm.io/rvm/install))
Sophie Brun's avatar
Sophie Brun committed
28
- Ruby >= 2.5 - Recommended: latest
Sophie Brun's avatar
Sophie Brun committed
29
  - Ruby 2.5.0 to 2.5.3 can cause an 'undefined symbol: rmpd_util_str_to_d' error in some systems, see [#1283](https://github.com/wpscanteam/wpscan/issues/1283)
Sophie Brun's avatar
Sophie Brun committed
30
- Curl >= 7.72  - Recommended: latest
Sophie Brun's avatar
Sophie Brun committed
31
  - The 7.29 has a segfault
Sophie Brun's avatar
Sophie Brun committed
32
  - The < 7.72 could result in `Stream error in the HTTP/2 framing layer` in some cases
Sophie Brun's avatar
Sophie Brun committed
33
- RubyGems      - Recommended: latest
Sophie Brun's avatar
Sophie Brun committed
34
- Nokogiri might require packages to be installed via your package manager depending on your OS, see https://nokogiri.org/tutorials/installing_nokogiri.html
Sophie Brun's avatar
Sophie Brun committed
35

Sophie Brun's avatar
Sophie Brun committed
36
37
38
39
### In a Pentesting distribution

When using a pentesting distubution (such as Kali Linux), it is recommended to install/update wpscan via the package manager if available.

Sophie Brun's avatar
Sophie Brun committed
40
41
42
43
### In macOSX via Homebrew

`brew install wpscanteam/tap/wpscan`

Sophie Brun's avatar
Sophie Brun committed
44
### From RubyGems
Sophie Brun's avatar
Sophie Brun committed
45

Sophie Brun's avatar
Sophie Brun committed
46
```shell
Sophie Brun's avatar
Sophie Brun committed
47
48
49
gem install wpscan
```

Sophie Brun's avatar
Sophie Brun committed
50
51
52
53
54
55
On MacOSX, if a ```Gem::FilePermissionError``` is raised due to the Apple's System Integrity Protection (SIP), either install RVM and install wpscan again, or run ```sudo gem install -n /usr/local/bin wpscan``` (see [#1286](https://github.com/wpscanteam/wpscan/issues/1286))

# Updating

You can update the local database by using ```wpscan --update```

Sophie Brun's avatar
Sophie Brun committed
56
Updating WPScan itself is either done via ```gem update wpscan``` or the packages manager (this is quite important for distributions such as in Kali Linux: ```apt-get update && apt-get upgrade```) depending on how WPScan was (pre)installed
Sophie Brun's avatar
Sophie Brun committed
57

Sophie Brun's avatar
Sophie Brun committed
58
59
60
61
# Docker

Pull the repo with ```docker pull wpscanteam/wpscan```

Sophie Brun's avatar
Sophie Brun committed
62
Enumerating usernames
Sophie Brun's avatar
Sophie Brun committed
63
64

```shell
Sophie Brun's avatar
Sophie Brun committed
65
66
67
68
docker run -it --rm wpscanteam/wpscan --url https://target.tld/ --enumerate u
```

Enumerating a range of usernames
Sophie Brun's avatar
Sophie Brun committed
69
70

```shell
Sophie Brun's avatar
Sophie Brun committed
71
72
docker run -it --rm wpscanteam/wpscan --url https://target.tld/ --enumerate u1-100
```
Sophie Brun's avatar
Sophie Brun committed
73

Sophie Brun's avatar
Sophie Brun committed
74
75
** replace u1-100 with a range of your choice.

Sophie Brun's avatar
Sophie Brun committed
76
77
# Usage

Sophie Brun's avatar
Sophie Brun committed
78
79
Full user documentation can be found here; https://github.com/wpscanteam/wpscan/wiki/WPScan-User-Documentation

Sophie Brun's avatar
Sophie Brun committed
80
81
82
```wpscan --url blog.tld``` This will scan the blog using default options with a good compromise between speed and accuracy. For example, the plugins will be checked passively but their version with a mixed detection mode (passively + aggressively). Potential config backup files will also be checked, along with other interesting findings.

If a more stealthy approach is required, then ```wpscan --stealthy --url blog.tld``` can be used.
Sophie Brun's avatar
Sophie Brun committed
83
84
85
86
87
88
As a result, when using the ```--enumerate``` option, don't forget to set the ```--plugins-detection``` accordingly, as its default is 'passive'.

For more options, open a terminal and type ```wpscan --help``` (if you built wpscan from the source, you should type the command outside of the git repo)

The DB is located at ~/.wpscan/db

Sophie Brun's avatar
Sophie Brun committed
89
90
91
92
93
94
95
96
97
## Optional: WordPress Vulnerability Database API

The WPScan CLI tool uses the [WordPress Vulnerability Database API](https://wpscan.com/api) to retrieve WordPress vulnerability data in real time. For WPScan to retrieve the vulnerability data an API token must be supplied via the `--api-token` option, or via a configuration file, as discussed below. An API token can be obtained by registering an account on [WPScan.com](https://wpscan.com/register).

Up to 25 API requests per day are given free of charge, that should be suitable to scan most WordPress websites at least once per day. When the daily 25 API requests are exhausted, WPScan will continue to work as normal but without any vulnerability data. Users can upgrade to paid API usage to increase their API limits within their user profile on [WPScan.com](https://wpscan.com/).

#### The Free plan allows 25 API requests per day. View the different [available API plans](https://wpscan.com/api).

### How many API requests do you need?
Sophie Brun's avatar
Sophie Brun committed
98

Sophie Brun's avatar
Sophie Brun committed
99
100
101
- Our WordPress scanner makes one API request for the WordPress version, one request per installed plugin and one request per installed theme.
- On average, a WordPress website has 22 installed plugins.
- The Free plan should cover around 50% of all WordPress websites.
Sophie Brun's avatar
Sophie Brun committed
102

Sophie Brun's avatar
Sophie Brun committed
103
104
## Load CLI options from file/s

Sophie Brun's avatar
Sophie Brun committed
105
106
WPScan can load all options (including the --url) from configuration files, the following locations are checked (order: first to last):

Sophie Brun's avatar
Sophie Brun committed
107
108
109
110
- ~/.wpscan/scan.json
- ~/.wpscan/scan.yml
- pwd/.wpscan/scan.json
- pwd/.wpscan/scan.yml
Sophie Brun's avatar
Sophie Brun committed
111

Sophie Brun's avatar
Sophie Brun committed
112
If those files exist, options from the `cli_options` key will be loaded and overridden if found twice.
Sophie Brun's avatar
Sophie Brun committed
113
114
115

e.g:

Sophie Brun's avatar
Sophie Brun committed
116
~/.wpscan/scan.yml:
Sophie Brun's avatar
Sophie Brun committed
117
118

```yml
Sophie Brun's avatar
Sophie Brun committed
119
120
121
cli_options:
  proxy: 'http://127.0.0.1:8080'
  verbose: true
Sophie Brun's avatar
Sophie Brun committed
122
123
```

Sophie Brun's avatar
Sophie Brun committed
124
pwd/.wpscan/scan.yml:
Sophie Brun's avatar
Sophie Brun committed
125
126

```yml
Sophie Brun's avatar
Sophie Brun committed
127
128
129
cli_options:
  proxy: 'socks5://127.0.0.1:9090'
  url: 'http://target.tld'
Sophie Brun's avatar
Sophie Brun committed
130
131
132
133
```

Running ```wpscan``` in the current directory (pwd), is the same as ```wpscan -v --proxy socks5://127.0.0.1:9090 --url http://target.tld```

Sophie Brun's avatar
Sophie Brun committed
134
135
136
137
138
139
140
141
142
## Save API Token in a file

The feature mentioned above is useful to keep the API Token in a config file and not have to supply it via the CLI each time. To do so, create the ~/.wpscan/scan.yml file containing the below:

```yml
cli_options:
  api_token: YOUR_API_TOKEN
```

Sophie Brun's avatar
Sophie Brun committed
143
## Load API Token From ENV (since v3.7.10)
Sophie Brun's avatar
Sophie Brun committed
144
145
146
147

The API Token will be automatically loaded from the ENV variable `WPSCAN_API_TOKEN` if present. If the `--api-token` CLI option is also provided, the value from the CLI will be used.


Sophie Brun's avatar
Sophie Brun committed
148
## Enumerating usernames
Sophie Brun's avatar
Sophie Brun committed
149
150

```shell
Sophie Brun's avatar
Sophie Brun committed
151
152
153
154
wpscan --url https://target.tld/ --enumerate u
```

Enumerating a range of usernames
Sophie Brun's avatar
Sophie Brun committed
155
156

```shell
Sophie Brun's avatar
Sophie Brun committed
157
158
159
wpscan --url https://target.tld/ --enumerate u1-100
```

Sophie Brun's avatar
Sophie Brun committed
160
** replace u1-100 with a range of your choice.
Sophie Brun's avatar
Sophie Brun committed
161

Sophie Brun's avatar
Sophie Brun committed
162
# LICENSE
Mati's avatar
Mati committed
163

Sophie Brun's avatar
Sophie Brun committed
164
## WPScan Public Source License
Sophie Brun's avatar
Sophie Brun committed
165

Sophie Brun's avatar
Sophie Brun committed
166
The WPScan software (henceforth referred to simply as "WPScan") is dual-licensed - Copyright 2011-2019 WPScan Team.
Sophie Brun's avatar
Sophie Brun committed
167
168
169

Cases that include commercialization of WPScan require a commercial, non-free license. Otherwise, WPScan can be used without charge under the terms set out below.

Sophie Brun's avatar
Sophie Brun committed
170
### 1. Definitions
Sophie Brun's avatar
Sophie Brun committed
171
172
173
174
175

1.1 "License" means this document.

1.2 "Contributor" means each individual or legal entity that creates, contributes to the creation of, or owns WPScan.

Sophie Brun's avatar
Sophie Brun committed
176
1.3 "WPScan Team" means WPScan’s core developers.
Sophie Brun's avatar
Sophie Brun committed
177

Sophie Brun's avatar
Sophie Brun committed
178
### 2. Commercialization
Sophie Brun's avatar
Sophie Brun committed
179
180
181
182
183

A commercial use is one intended for commercial advantage or monetary compensation.

Example cases of commercialization are:

Sophie Brun's avatar
Sophie Brun committed
184
185
186
- Using WPScan to provide commercial managed/Software-as-a-Service services.
- Distributing WPScan as a commercial product or as part of one.
- Using WPScan as a value added service/product.
Sophie Brun's avatar
Sophie Brun committed
187
188
189

Example cases which do not require a commercial license, and thus fall under the terms set out below, include (but are not limited to):

Sophie Brun's avatar
Sophie Brun committed
190
191
192
193
- Penetration testers (or penetration testing organizations) using WPScan as part of their assessment toolkit.
- Penetration Testing Linux Distributions including but not limited to Kali Linux, SamuraiWTF, BackBox Linux.
- Using WPScan to test your own systems.
- Any non-commercial use of WPScan.
Sophie Brun's avatar
Sophie Brun committed
194

Sophie Brun's avatar
Sophie Brun committed
195
If you need to purchase a commercial license or are unsure whether you need to purchase a commercial license contact us - contact@wpscan.com.
Sophie Brun's avatar
Sophie Brun committed
196
197
198

Free-use Terms and Conditions;

Sophie Brun's avatar
Sophie Brun committed
199
### 3. Redistribution
Sophie Brun's avatar
Sophie Brun committed
200
201

Redistribution is permitted under the following conditions:
Mati's avatar
Mati committed
202

Sophie Brun's avatar
Sophie Brun committed
203
204
205
- Unmodified License is provided with WPScan.
- Unmodified Copyright notices are provided with WPScan.
- Does not conflict with the commercialization clause.
Mati's avatar
Mati committed
206

Sophie Brun's avatar
Sophie Brun committed
207
### 4. Copying
Mati's avatar
Mati committed
208

Sophie Brun's avatar
Sophie Brun committed
209
Copying is permitted so long as it does not conflict with the Redistribution clause.
Mati's avatar
Mati committed
210

Sophie Brun's avatar
Sophie Brun committed
211
### 5. Modification
Sophie Brun's avatar
Sophie Brun committed
212

Sophie Brun's avatar
Sophie Brun committed
213
Modification is permitted so long as it does not conflict with the Redistribution clause.
Sophie Brun's avatar
Sophie Brun committed
214

Sophie Brun's avatar
Sophie Brun committed
215
### 6. Contributions
Sophie Brun's avatar
Sophie Brun committed
216

Sophie Brun's avatar
Sophie Brun committed
217
Any Contributions assume the Contributor grants the WPScan Team the unlimited, non-exclusive right to reuse, modify and relicense the Contributor's content.
Sophie Brun's avatar
Sophie Brun committed
218

Sophie Brun's avatar
Sophie Brun committed
219
### 7. Support
Sophie Brun's avatar
Sophie Brun committed
220
221
222

WPScan is provided under an AS-IS basis and without any support, updates or maintenance. Support, updates and maintenance may be given according to the sole discretion of the WPScan Team.

Sophie Brun's avatar
Sophie Brun committed
223
### 8. Disclaimer of Warranty
Sophie Brun's avatar
Sophie Brun committed
224
225
226

WPScan is provided under this License on an “as is” basis, without warranty of any kind, either expressed, implied, or statutory, including, without limitation, warranties that the WPScan is free of defects, merchantable, fit for a particular purpose or non-infringing.

Sophie Brun's avatar
Sophie Brun committed
227
### 9. Limitation of Liability
Sophie Brun's avatar
Sophie Brun committed
228
229
230

To the extent permitted under Law, WPScan is provided under an AS-IS basis. The WPScan Team shall never, and without any limit, be liable for any damage, cost, expense or any other payment incurred as a result of WPScan's actions, failure, bugs and/or any other interaction between WPScan and end-equipment, computers, other software or any 3rd party, end-equipment, computer or services.

Sophie Brun's avatar
Sophie Brun committed
231
### 10. Disclaimer
Sophie Brun's avatar
Sophie Brun committed
232
233

Running WPScan against websites without prior mutual consent may be illegal in your country. The WPScan Team accept no liability and are not responsible for any misuse or damage caused by WPScan.
Mati's avatar
Mati committed
234

Sophie Brun's avatar
Sophie Brun committed
235
236
237
### 11. Trademark

The "wpscan" term is a registered trademark. This License does not grant the use of the "wpscan" trademark or the use of the WPScan logo.