11 | Welcome to this security demo. The purpose of this application is to demonstrate security vulnerabilities through an application that doesn't implement any mitigation techniques. This particular application is used for demonstrating Cross-Site Scripting (XSS), Cross-Site Request Forgery and Clickjacking vulnerabilities.
12 |
11 | Welcome to this security demo. The purpose of this application is to demonstrate how to attack security vulnerabilities through an application that doesn't implement any mitigation techniques. This particular application is used for demonstrating attacks with Cross-Site Scripting (XSS), Cross-Site Request Forgery and Clickjacking vulnerabilities.
12 |
Make sure the REMOTE server is running
25 | Click on a description title to narrow the scope to just its specs
26 | (see "
27 | ?grep" in address bar).
28 | Click on a spec title to see the test implementation.
29 | Click on page title to start over.
30 |
Make sure the REMOTE server is running
25 | Click on a description title to narrow the scope to just its specs
26 | (see "
27 | ?grep" in address bar).
28 | Click on a spec title to see the test implementation.
29 | Click on page title to start over.
30 |
' +
27 | '' +
28 | '');
29 |
30 | // The spec examines changes to these template parts
31 | dropdownElement = el.find('.sidebar-dropdown a'); // the link to click
32 | innerElement = el.find('.sidebar-inner'); // container of menu items
33 |
34 | // ng's $compile service resolves nested directives (there are none in this example)
35 | // and binds the element to the scope (which must be a real ng scope)
36 | scope = $rootScope;
37 | $compile(el)(scope);
38 |
39 | // tell angular to look at the scope values right now
40 | scope.$digest();
41 | }));
42 |
43 | /// tests ///
44 | describe('the isOpenClass', function () {
45 | it('is absent for a closed menu', function () {
46 | hasIsOpenClass(false);
47 | });
48 |
49 | it('is added to a closed menu after clicking', function () {
50 | clickIt();
51 | hasIsOpenClass(true);
52 | });
53 |
54 | it('is present for an open menu', function () {
55 | openDropdown();
56 | hasIsOpenClass(true);
57 | });
58 |
59 | it('is removed from a closed menu after clicking', function () {
60 | openDropdown();
61 | clickIt();
62 | hasIsOpenClass(false);
63 | });
64 | });
65 |
66 | describe('when animating w/ jQuery fx off', function () {
67 | beforeEach(function () {
68 | // remember current state of jQuery's global FX duration switch
69 | this.oldFxOff = $.fx.off;
70 | // when jQuery fx are of, there is zero animation time; no waiting for animation to complete
71 | $.fx.off = true;
72 | // must add to DOM when testing jQuery animation result
73 | el.appendTo(document.body);
74 | });
75 |
76 | afterEach(function () {
77 | $.fx.off = this.oldFxOff;
78 | el.remove();
79 | });
80 |
81 | it('dropdown is visible after opening a closed menu', function () {
82 | dropdownIsVisible(false); // hidden before click
83 | clickIt();
84 | dropdownIsVisible(true); // visible after click
85 | });
86 |
87 | it('dropdown is hidden after closing an open menu', function () {
88 | openDropdown();
89 | dropdownIsVisible(true); // visible before click
90 | clickIt();
91 | dropdownIsVisible(false); // hidden after click
92 | });
93 |
94 | it('click triggers "when-done-animating" expression', function () {
95 | // spy on directive's callback when the animation is done
96 | var spy = sinon.spy();
97 |
98 | // Recall the pertinent tag in the template ...
99 | // '
100 | // therefore, the directive looks for scope.vm.sidebarReady
101 | // and should call that method with the value '42'
102 | scope.vm = {sidebarReady: spy};
103 |
104 | // tell angular to look again for that vm.sidebarReady property
105 | scope.$digest();
106 |
107 | // spy not called until after click which triggers the animation
108 | expect(spy).not.to.have.been.called;
109 |
110 | // this click triggers an animation
111 | clickIt();
112 |
113 | // verify that the vm's method (sidebarReady) was called with '42'
114 | // FYI: spy.args[0] is the array of args passed to sidebarReady()
115 | expect(spy).to.have.been.called;
116 | expect(spy).to.have.been.calledWith(42);
117 | });
118 | });
119 |
120 | /////// helpers //////
121 |
122 | // put the dropdown in the 'menu open' state
123 | function openDropdown() {
124 | dropdownElement.addClass(isOpenClass);
125 | innerElement.css('display', 'block');
126 | }
127 |
128 | // click the "menu" link
129 | function clickIt() {
130 | dropdownElement.trigger('click');
131 | }
132 |
133 | // assert whether the "menu" link has the class that means 'is open'
134 | function hasIsOpenClass(isTrue) {
135 | var hasClass = dropdownElement.hasClass(isOpenClass);
136 | expect(hasClass).equal(!!isTrue,
137 | 'dropdown has the "is open" class is ' + hasClass);
138 | }
139 |
140 | // assert whether the dropdown container is 'block' (visible) or 'none' (hidden)
141 | function dropdownIsVisible(isTrue) {
142 | var display = innerElement.css('display');
143 | expect(display).to.equal(isTrue ? 'block' : 'none',
144 | 'innerElement display value is ' + display);
145 | }
146 | });
147 |
--------------------------------------------------------------------------------
/attacker-app/src/client/app/layout/ht-sidebar.directive.spec.js:
--------------------------------------------------------------------------------
1 | /* jshint -W117, -W030 */
2 | /* jshint multistr:true */
3 | describe('htSidebar directive: ', function () {
4 | var dropdownElement;
5 | var el;
6 | var innerElement;
7 | var isOpenClass = 'dropy';
8 | var scope;
9 |
10 | beforeEach(module('app.layout'));
11 |
12 | beforeEach(inject(function($compile, $rootScope) {
13 | // The minimum necessary template HTML for this spec.
14 | // Simulates a menu link that opens and closes a dropdown of menu items
15 | // The `when-done-animating` attribute is optional (as is the vm's implementation)
16 | //
17 | // N.B.: the attribute value is supposed to be an expression that invokes a $scope method
18 | // so make sure the expression includes '()', e.g., "vm.sidebarReady(42)"
19 | // no harm if the expression fails ... but then scope.sidebarReady will be undefined.
20 | // All parameters in the expression are passed to vm.sidebarReady ... if it exists
21 | //
22 | // N.B.: We do NOT add this element to the browser DOM (although we could).
23 | // spec runs faster if we don't touch the DOM (even the PhantomJS DOM).
24 | el = angular.element(
25 | '' +
26 | '
' +
27 | '' +
28 | '');
29 |
30 | // The spec examines changes to these template parts
31 | dropdownElement = el.find('.sidebar-dropdown a'); // the link to click
32 | innerElement = el.find('.sidebar-inner'); // container of menu items
33 |
34 | // ng's $compile service resolves nested directives (there are none in this example)
35 | // and binds the element to the scope (which must be a real ng scope)
36 | scope = $rootScope;
37 | $compile(el)(scope);
38 |
39 | // tell angular to look at the scope values right now
40 | scope.$digest();
41 | }));
42 |
43 | /// tests ///
44 | describe('the isOpenClass', function () {
45 | it('is absent for a closed menu', function () {
46 | hasIsOpenClass(false);
47 | });
48 |
49 | it('is added to a closed menu after clicking', function () {
50 | clickIt();
51 | hasIsOpenClass(true);
52 | });
53 |
54 | it('is present for an open menu', function () {
55 | openDropdown();
56 | hasIsOpenClass(true);
57 | });
58 |
59 | it('is removed from a closed menu after clicking', function () {
60 | openDropdown();
61 | clickIt();
62 | hasIsOpenClass(false);
63 | });
64 | });
65 |
66 | describe('when animating w/ jQuery fx off', function () {
67 | beforeEach(function () {
68 | // remember current state of jQuery's global FX duration switch
69 | this.oldFxOff = $.fx.off;
70 | // when jQuery fx are of, there is zero animation time; no waiting for animation to complete
71 | $.fx.off = true;
72 | // must add to DOM when testing jQuery animation result
73 | el.appendTo(document.body);
74 | });
75 |
76 | afterEach(function () {
77 | $.fx.off = this.oldFxOff;
78 | el.remove();
79 | });
80 |
81 | it('dropdown is visible after opening a closed menu', function () {
82 | dropdownIsVisible(false); // hidden before click
83 | clickIt();
84 | dropdownIsVisible(true); // visible after click
85 | });
86 |
87 | it('dropdown is hidden after closing an open menu', function () {
88 | openDropdown();
89 | dropdownIsVisible(true); // visible before click
90 | clickIt();
91 | dropdownIsVisible(false); // hidden after click
92 | });
93 |
94 | it('click triggers "when-done-animating" expression', function () {
95 | // spy on directive's callback when the animation is done
96 | var spy = sinon.spy();
97 |
98 | // Recall the pertinent tag in the template ...
99 | // '
100 | // therefore, the directive looks for scope.vm.sidebarReady
101 | // and should call that method with the value '42'
102 | scope.vm = {sidebarReady: spy};
103 |
104 | // tell angular to look again for that vm.sidebarReady property
105 | scope.$digest();
106 |
107 | // spy not called until after click which triggers the animation
108 | expect(spy).not.to.have.been.called;
109 |
110 | // this click triggers an animation
111 | clickIt();
112 |
113 | // verify that the vm's method (sidebarReady) was called with '42'
114 | // FYI: spy.args[0] is the array of args passed to sidebarReady()
115 | expect(spy).to.have.been.called;
116 | expect(spy).to.have.been.calledWith(42);
117 | });
118 | });
119 |
120 | /////// helpers //////
121 |
122 | // put the dropdown in the 'menu open' state
123 | function openDropdown() {
124 | dropdownElement.addClass(isOpenClass);
125 | innerElement.css('display', 'block');
126 | }
127 |
128 | // click the "menu" link
129 | function clickIt() {
130 | dropdownElement.trigger('click');
131 | }
132 |
133 | // assert whether the "menu" link has the class that means 'is open'
134 | function hasIsOpenClass(isTrue) {
135 | var hasClass = dropdownElement.hasClass(isOpenClass);
136 | expect(hasClass).equal(!!isTrue,
137 | 'dropdown has the "is open" class is ' + hasClass);
138 | }
139 |
140 | // assert whether the dropdown container is 'block' (visible) or 'none' (hidden)
141 | function dropdownIsVisible(isTrue) {
142 | var display = innerElement.css('display');
143 | expect(display).to.equal(isTrue ? 'block' : 'none',
144 | 'innerElement display value is ' + display);
145 | }
146 | });
147 |
--------------------------------------------------------------------------------
/attacker-app/README.md:
--------------------------------------------------------------------------------
1 | # attacker-app
2 |
3 | **Generated from HotTowel Angular**
4 |
5 | >*Opinionated Angular style guide for teams by [@john_papa](//twitter.com/john_papa)*
6 |
7 | >More details about the styles and patterns used in this app can be found in my [Angular Style Guide](https://github.com/johnpapa/angularjs-styleguide) and my [Angular Patterns: Clean Code](http://jpapa.me/ngclean) course at [Pluralsight](http://pluralsight.com/training/Authors/Details/john-papa) and working in teams.
8 |
9 | ## Prerequisites
10 |
11 | 1. Install [Node.js](http://nodejs.org)
12 | - on OSX use [homebrew](http://brew.sh) `brew install node`
13 | - on Windows use [chocolatey](https://chocolatey.org/) `choco install nodejs`
14 |
15 | 2. Install Yeoman `npm install -g yo`
16 |
17 | 3. Install these NPM packages globally
18 |
19 | ```bash
20 | npm install -g bower gulp nodemon
21 | ```
22 |
23 | >Refer to these [instructions on how to not require sudo](https://github.com/sindresorhus/guides/blob/master/npm-global-without-sudo.md)
24 |
25 | ## Running HotTowel
26 |
27 | ### Linting
28 | - Run code analysis using `gulp vet`. This runs jshint, jscs, and plato.
29 |
30 | ### Tests
31 | - Run the unit tests using `gulp test` (via karma, mocha, sinon).
32 |
33 | ### Running in dev mode
34 | - Run the project with `gulp serve-dev`
35 |
36 | - opens it in a browser and updates the browser with any files changes.
37 |
38 | ### Building the project
39 | - Build the optimized project using `gulp build`
40 | - This create the optimized code for the project and puts it in the build folder
41 |
42 | ### Running the optimized code
43 | - Run the optimize project from the build folder with `gulp serve-build`
44 |
45 | ## Exploring HotTowel
46 | HotTowel Angular starter project
47 |
48 | ### Structure
49 | The structure also contains a gulpfile.js and a server folder. The server is there just so we can serve the app using node. Feel free to use any server you wish.
50 |
51 | /src
52 | /client
53 | /app
54 | /content
55 |
56 | ### Installing Packages
57 | When you generate the project it should run these commands, but if you notice missing packages, run these again:
58 |
59 | - `npm install`
60 | - `bower install`
61 |
62 | ### The Modules
63 | The app has 4 feature modules and depends on a series of external modules and custom but cross-app modules
64 |
65 | ```
66 | app --> [
67 | app.admin --> [
68 | app.core,
69 | app.widgets
70 | ],
71 | app.dashboard --> [
72 | app.core,
73 | app.widgets
74 | ],
75 | app.layout --> [
76 | app.core
77 | ],
78 | app.widgets,
79 | app.core --> [
80 | ngAnimate,
81 | ngSanitize,
82 | ui.router,
83 | blocks.exception,
84 | blocks.logger,
85 | blocks.router
86 | ]
87 | ]
88 | ```
89 |
90 | #### core Module
91 | Core modules are ones that are shared throughout the entire application and may be customized for the specific application. Example might be common data services.
92 |
93 | This is an aggregator of modules that the application will need. The `core` module takes the blocks, common, and Angular sub-modules as dependencies.
94 |
95 | #### blocks Modules
96 | Block modules are reusable blocks of code that can be used across projects simply by including them as dependencies.
97 |
98 | ##### blocks.logger Module
99 | The `blocks.logger` module handles logging across the Angular app.
100 |
101 | ##### blocks.exception Module
102 | The `blocks.exception` module handles exceptions across the Angular app.
103 |
104 | It depends on the `blocks.logger` module, because the implementation logs the exceptions.
105 |
106 | ##### blocks.router Module
107 | The `blocks.router` module contains a routing helper module that assists in adding routes to the $routeProvider.
108 |
109 | ## Gulp Tasks
110 |
111 | ### Task Listing
112 |
113 | - `gulp help`
114 |
115 | Displays all of the available gulp tasks.
116 |
117 | ### Code Analysis
118 |
119 | - `gulp vet`
120 |
121 | Performs static code analysis on all javascript files. Runs jshint and jscs.
122 |
123 | - `gulp vet --verbose`
124 |
125 | Displays all files affected and extended information about the code analysis.
126 |
127 | - `gulp plato`
128 |
129 | Performs code analysis using plato on all javascript files. Plato generates a report in the reports folder.
130 |
131 | ### Testing
132 |
133 | - `gulp serve-specs`
134 |
135 | Serves and browses to the spec runner html page and runs the unit tests in it. Injects any changes on the fly and re runs the tests. Quick and easy view of tests as an alternative to terminal via `gulp test`.
136 |
137 | - `gulp test`
138 |
139 | Runs all unit tests using karma runner, mocha, chai and sinon with phantomjs. Depends on vet task, for code analysis.
140 |
141 | - `gulp test --startServers`
142 |
143 | Runs all unit tests and midway tests. Cranks up a second node process to run a server for the midway tests to hit a web api.
144 |
145 | - `gulp autotest`
146 |
147 | Runs a watch to run all unit tests.
148 |
149 | - `gulp autotest --startServers`
150 |
151 | Runs a watch to run all unit tests and midway tests. Cranks up a second node process to run a server for the midway tests to hit a web api.
152 |
153 | ### Cleaning Up
154 |
155 | - `gulp clean`
156 |
157 | Remove all files from the build and temp folders
158 |
159 | - `gulp clean-images`
160 |
161 | Remove all images from the build folder
162 |
163 | - `gulp clean-code`
164 |
165 | Remove all javascript and html from the build folder
166 |
167 | - `gulp clean-fonts`
168 |
169 | Remove all fonts from the build folder
170 |
171 | - `gulp clean-styles`
172 |
173 | Remove all styles from the build folder
174 |
175 | ### Fonts and Images
176 |
177 | - `gulp fonts`
178 |
179 | Copy all fonts from source to the build folder
180 |
181 | - `gulp images`
182 |
183 | Copy all images from source to the build folder
184 |
185 | ### Styles
186 |
187 | - `gulp styles`
188 |
189 | Compile less files to CSS, add vendor prefixes, and copy to the build folder
190 |
191 | ### Bower Files
192 |
193 | - `gulp wiredep`
194 |
195 | Looks up all bower components' main files and JavaScript source code, then adds them to the `index.html`.
196 |
197 | The `.bowerrc` file also runs this as a postinstall task whenever `bower install` is run.
198 |
199 | ### Angular HTML Templates
200 |
201 | - `gulp templatecache`
202 |
203 | Create an Angular module that adds all HTML templates to Angular's $templateCache. This pre-fetches all HTML templates saving XHR calls for the HTML.
204 |
205 | - `gulp templatecache --verbose`
206 |
207 | Displays all files affected by the task.
208 |
209 | ### Serving Development Code
210 |
211 | - `gulp serve-dev`
212 |
213 | Serves the development code and launches it in a browser. The goal of building for development is to do it as fast as possible, to keep development moving efficiently. This task serves all code from the source folders and compiles less to css in a temp folder.
214 |
215 | - `gulp serve-dev --nosync`
216 |
217 | Serves the development code without launching the browser.
218 |
219 | - `gulp serve-dev --debug`
220 |
221 | Launch debugger with node-inspector.
222 |
223 | - `gulp serve-dev --debug-brk`
224 |
225 | Launch debugger and break on 1st line with node-inspector.
226 |
227 | ### Building Production Code
228 |
229 | - `gulp optimize`
230 |
231 | Optimize all javascript and styles, move to a build folder, and inject them into the new index.html
232 |
233 | - `gulp build`
234 |
235 | Copies all fonts, copies images and runs `gulp optimize` to build the production code to the build folder.
236 |
237 | ### Serving Production Code
238 |
239 | - `gulp serve-build`
240 |
241 | Serve the optimized code from the build folder and launch it in a browser.
242 |
243 | - `gulp serve-build --nosync`
244 |
245 | Serve the optimized code from the build folder and manually launch the browser.
246 |
247 | - `gulp serve-build --debug`
248 |
249 | Launch debugger with node-inspector.
250 |
251 | - `gulp serve-build --debug-brk`
252 |
253 | Launch debugger and break on 1st line with node-inspector.
254 |
255 | ### Bumping Versions
256 |
257 | - `gulp bump`
258 |
259 | Bump the minor version using semver.
260 | --type=patch // default
261 | --type=minor
262 | --type=major
263 | --type=pre
264 | --ver=1.2.3 // specific version
265 |
266 | ## License
267 |
268 | MIT
269 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # vulnerable-app & attacker-app
2 | There are two applications within this repository that were generated from the HotTowel Angular generator. The main one is the `vulnerable-app` which is found in the `/src` folder. This application was built intentionally built out with vulnerabilities to easily demonstrate how they are performed by an attacker. The secondary application is the `attacker-app` found in the `/attacker-app` folder and it was built out to assist in demonstrating an attacker's website that is exploiting the vulnerabilities in the `vulnerable-app`.
3 |
4 | ## Requirements
5 | 1. Node.js v4.2.x
6 | 2. NPM v3.10.x
7 |
8 | > Straying from these versions may result in unanticipated behavior and it cannot be guaranteed the app will produce the expected results.
9 |
10 | ## How to Run Both Apps
11 | 1. Open your terminal and `cd` to the root folder for this repository
12 | 2. Run `gulp serve-dev` to spin up the `vulnerable-app`
13 | 3. You should see your browser open up a new tab to the following URL: [http://localhost:3000](http://localhost:3000)
14 | 4. Open a new terminal window or tab and `cd` to the `/attacker-app` folder from the root location of this repository
15 | 5. Run `gulp serve-dev`
16 | 6. You should see your browser open up another new tab to the following URL: [http://localhost:3002](http://localhost:3002)
17 |
18 | ## How to Test
19 |
20 | ### XSS
21 | The following steps will demonstrate a simple example of being able to escape the context of where the search input text is printed on screen and used to execute an injectable script that the browser will execute.
22 |
23 | 1. In the tab that's running the `vulnerable-app`, click on the option `XSS-Search` in the navigation bar
24 | 2. In the "Search" field enter the following text: ``
25 | 3. Click the "Submit" button
26 | 4. You should see an alert message pop up on your screen with the message "Malicious Script!"
27 |
28 | ### CSRF
29 | The following steps will demonstrate a simple example of being able to submit requests on behalf of the logged in user within the vulnerable-app, but executed from the `attacker-app`.
30 |
31 | 1. In the tab that's running the `vulnerable-app`, click on the option `CSRF` in the navigation bar and take note of the "User Profile" section within the view
32 | > By default, the user's "First Name" should show the value of `Jim` and the "Last Name" as the value of `Bob`
33 |
34 | 2. In the tab that's running the `attacker-app`, click on the option `CSRF-Attack` in the navigation bar. This will immediately execute the CSRF attack and display the forged POST data
35 | 3. Go back to the tab that's running the `vulnerable-app` and make sure you're still in the `CSRF` view
36 | 4. Click the "Get Latest User Profile" button and you should see that the user's profile was changed due to the CSRF attack
37 |
38 | > The user's "First Name" should show the value of `Evil` and the "Last Name" as the value of `Hacker` now
39 |
40 | ### Clickjacking
41 | The following steps will demonstrate a simple example of clickjacking by tricking the user of the `vulnerable-app` to click a seemingly harmless button in the `attacker-app` that actually executes an action in the `vulnerable-app`.
42 |
43 | 1. In the tab that's running the `attacker-app`, click on the option `Clickjacking-Attack`
44 | > You should be able to see that the `vulnerable-app` is loaded in the view, but with a low opacity
45 |
46 | 2. Open the developer tools for the browser you're using and view the console
47 | 3. Click the "Click to see awesome dog backflips!" button
48 |
49 | > You should see a message in the console with the following text: "The profile was successfully deleted!"
50 |
51 | This example demonstrates that while the user thinks they're clicking on a button that will show them "awesome dog backflips", they're actually clicking on the "Delete Sensitive Information!" button found in the `vulnerable-app`. This is accomplished because the `attacker-app` can load the `vulnerable-app` in an `iframe` html element, style the iframe so it's not visible at all (in this case it is somewhat visible for demonstration purposes) and actually a "layer" deep from other html elements within the view, and place "clickbait" type elements on top of the iframe and over the areas the attacker wants the user to click within the iframe instead.
52 |
53 | ## References/Further Reading
54 | 1. [OWASP](https://www.owasp.org/)
55 | 1. [Cross-site Scripting Defense Cheat Sheet][1]
56 | 1. [Cross-site Request Forgery Defense Cheat Sheet][2]
57 | 1. [Clickjacking Defense Cheat Sheet](https://www.owasp.org/index.php/Clickjacking_Defense_Cheat_Sheet)
58 | 2. [HTML5Rocks - CSP](http://www.html5rocks.com/en/tutorials/security/content-security-policy/)
59 | 3. [Angular $sanitize](https://docs.angularjs.org/api/ngSanitize/service/$sanitize)
60 | 4. [Angular $sce](https://docs.angularjs.org/api/ng/service/$sce)
61 | 5. [xss-filters](https://www.npmjs.com/package/xss-filters)
62 | 6. [lusca](https://www.npmjs.com/package/lusca)
63 |
64 | [1]: https://www.owasp.org/index.php/XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet
65 | [2]: https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet
66 |
67 | -------
68 |
69 | **Generated from HotTowel Angular**
70 |
71 | >*Opinionated Angular style guide for teams by [@john_papa](//twitter.com/john_papa)*
72 |
73 | >More details about the styles and patterns used in this app can be found in my [Angular Style Guide](https://github.com/johnpapa/angularjs-styleguide) and my [Angular Patterns: Clean Code](http://jpapa.me/ngclean) course at [Pluralsight](http://pluralsight.com/training/Authors/Details/john-papa) and working in teams.
74 |
75 | ## Prerequisites
76 |
77 | 1. Install [Node.js](http://nodejs.org)
78 | - on OSX use [homebrew](http://brew.sh) `brew install node`
79 | - on Windows use [chocolatey](https://chocolatey.org/) `choco install nodejs`
80 |
81 | 2. Install Yeoman `npm install -g yo`
82 |
83 | 3. Install these NPM packages globally
84 |
85 | ```bash
86 | npm install -g bower gulp nodemon
87 | ```
88 |
89 | >Refer to these [instructions on how to not require sudo](https://github.com/sindresorhus/guides/blob/master/npm-global-without-sudo.md)
90 |
91 | ## Running HotTowel
92 |
93 | ### Linting
94 | - Run code analysis using `gulp vet`. This runs jshint, jscs, and plato.
95 |
96 | ### Tests
97 | - Run the unit tests using `gulp test` (via karma, mocha, sinon).
98 |
99 | ### Running in dev mode
100 | - Run the project with `gulp serve-dev`
101 |
102 | - opens it in a browser and updates the browser with any files changes.
103 |
104 | ### Building the project
105 | - Build the optimized project using `gulp build`
106 | - This create the optimized code for the project and puts it in the build folder
107 |
108 | ### Running the optimized code
109 | - Run the optimize project from the build folder with `gulp serve-build`
110 |
111 | ## Exploring HotTowel
112 | HotTowel Angular starter project
113 |
114 | ### Structure
115 | The structure also contains a gulpfile.js and a server folder. The server is there just so we can serve the app using node. Feel free to use any server you wish.
116 |
117 | /src
118 | /client
119 | /app
120 | /content
121 |
122 | ### Installing Packages
123 | When you generate the project it should run these commands, but if you notice missing packages, run these again:
124 |
125 | - `npm install`
126 | - `bower install`
127 |
128 | ### The Modules
129 | The app has 4 feature modules and depends on a series of external modules and custom but cross-app modules
130 |
131 | ```
132 | app --> [
133 | app.admin --> [
134 | app.core,
135 | app.widgets
136 | ],
137 | app.dashboard --> [
138 | app.core,
139 | app.widgets
140 | ],
141 | app.layout --> [
142 | app.core
143 | ],
144 | app.widgets,
145 | app.core --> [
146 | ngAnimate,
147 | ngSanitize,
148 | ui.router,
149 | blocks.exception,
150 | blocks.logger,
151 | blocks.router
152 | ]
153 | ]
154 | ```
155 |
156 | #### core Module
157 | Core modules are ones that are shared throughout the entire application and may be customized for the specific application. Example might be common data services.
158 |
159 | This is an aggregator of modules that the application will need. The `core` module takes the blocks, common, and Angular sub-modules as dependencies.
160 |
161 | #### blocks Modules
162 | Block modules are reusable blocks of code that can be used across projects simply by including them as dependencies.
163 |
164 | ##### blocks.logger Module
165 | The `blocks.logger` module handles logging across the Angular app.
166 |
167 | ##### blocks.exception Module
168 | The `blocks.exception` module handles exceptions across the Angular app.
169 |
170 | It depends on the `blocks.logger` module, because the implementation logs the exceptions.
171 |
172 | ##### blocks.router Module
173 | The `blocks.router` module contains a routing helper module that assists in adding routes to the $routeProvider.
174 |
175 | ## Gulp Tasks
176 |
177 | ### Task Listing
178 |
179 | - `gulp help`
180 |
181 | Displays all of the available gulp tasks.
182 |
183 | ### Code Analysis
184 |
185 | - `gulp vet`
186 |
187 | Performs static code analysis on all javascript files. Runs jshint and jscs.
188 |
189 | - `gulp vet --verbose`
190 |
191 | Displays all files affected and extended information about the code analysis.
192 |
193 | - `gulp plato`
194 |
195 | Performs code analysis using plato on all javascript files. Plato generates a report in the reports folder.
196 |
197 | ### Testing
198 |
199 | - `gulp serve-specs`
200 |
201 | Serves and browses to the spec runner html page and runs the unit tests in it. Injects any changes on the fly and re runs the tests. Quick and easy view of tests as an alternative to terminal via `gulp test`.
202 |
203 | - `gulp test`
204 |
205 | Runs all unit tests using karma runner, mocha, chai and sinon with phantomjs. Depends on vet task, for code analysis.
206 |
207 | - `gulp test --startServers`
208 |
209 | Runs all unit tests and midway tests. Cranks up a second node process to run a server for the midway tests to hit a web api.
210 |
211 | - `gulp autotest`
212 |
213 | Runs a watch to run all unit tests.
214 |
215 | - `gulp autotest --startServers`
216 |
217 | Runs a watch to run all unit tests and midway tests. Cranks up a second node process to run a server for the midway tests to hit a web api.
218 |
219 | ### Cleaning Up
220 |
221 | - `gulp clean`
222 |
223 | Remove all files from the build and temp folders
224 |
225 | - `gulp clean-images`
226 |
227 | Remove all images from the build folder
228 |
229 | - `gulp clean-code`
230 |
231 | Remove all javascript and html from the build folder
232 |
233 | - `gulp clean-fonts`
234 |
235 | Remove all fonts from the build folder
236 |
237 | - `gulp clean-styles`
238 |
239 | Remove all styles from the build folder
240 |
241 | ### Fonts and Images
242 |
243 | - `gulp fonts`
244 |
245 | Copy all fonts from source to the build folder
246 |
247 | - `gulp images`
248 |
249 | Copy all images from source to the build folder
250 |
251 | ### Styles
252 |
253 | - `gulp styles`
254 |
255 | Compile less files to CSS, add vendor prefixes, and copy to the build folder
256 |
257 | ### Bower Files
258 |
259 | - `gulp wiredep`
260 |
261 | Looks up all bower components' main files and JavaScript source code, then adds them to the `index.html`.
262 |
263 | The `.bowerrc` file also runs this as a postinstall task whenever `bower install` is run.
264 |
265 | ### Angular HTML Templates
266 |
267 | - `gulp templatecache`
268 |
269 | Create an Angular module that adds all HTML templates to Angular's $templateCache. This pre-fetches all HTML templates saving XHR calls for the HTML.
270 |
271 | - `gulp templatecache --verbose`
272 |
273 | Displays all files affected by the task.
274 |
275 | ### Serving Development Code
276 |
277 | - `gulp serve-dev`
278 |
279 | Serves the development code and launches it in a browser. The goal of building for development is to do it as fast as possible, to keep development moving efficiently. This task serves all code from the source folders and compiles less to css in a temp folder.
280 |
281 | - `gulp serve-dev --nosync`
282 |
283 | Serves the development code without launching the browser.
284 |
285 | - `gulp serve-dev --debug`
286 |
287 | Launch debugger with node-inspector.
288 |
289 | - `gulp serve-dev --debug-brk`
290 |
291 | Launch debugger and break on 1st line with node-inspector.
292 |
293 | ### Building Production Code
294 |
295 | - `gulp optimize`
296 |
297 | Optimize all javascript and styles, move to a build folder, and inject them into the new index.html
298 |
299 | - `gulp build`
300 |
301 | Copies all fonts, copies images and runs `gulp optimize` to build the production code to the build folder.
302 |
303 | ### Serving Production Code
304 |
305 | - `gulp serve-build`
306 |
307 | Serve the optimized code from the build folder and launch it in a browser.
308 |
309 | - `gulp serve-build --nosync`
310 |
311 | Serve the optimized code from the build folder and manually launch the browser.
312 |
313 | - `gulp serve-build --debug`
314 |
315 | Launch debugger with node-inspector.
316 |
317 | - `gulp serve-build --debug-brk`
318 |
319 | Launch debugger and break on 1st line with node-inspector.
320 |
321 | ### Bumping Versions
322 |
323 | - `gulp bump`
324 |
325 | Bump the minor version using semver.
326 | --type=patch // default
327 | --type=minor
328 | --type=major
329 | --type=pre
330 | --ver=1.2.3 // specific version
331 |
332 | ## License
333 |
334 | MIT
335 |
336 | ## Credits
337 | This a fork of [Clarkio](https://github.com/clarkio)'s [vulnerable-app](https://github.com/clarkio/vulnerable-app) repo.
338 |
--------------------------------------------------------------------------------