|
1 | 1 | # LandingPage secureCodeBox |
2 | 2 |
|
3 | | -This repository sources the [securecodebox.io] website. Our webpage is meant to provide an extensive documentation about our [secureCodeBox] and many helpful guides on how to start and operate it. The website is build with the [GatsbyJS] Framework and hosted through [GitHub Pages]. All important decision about this website are documented in our `/adr` folder. If you want to contribute to our website, please follow the Style Guide down below. |
4 | | - |
5 | | -## Build and Run |
6 | | - |
7 | | -In order to build and run this website you need to install [Node.js and NPM] for your platform. |
8 | | -Finally you download/clone this repository and install all required Node modules: |
9 | | - |
10 | | -```bash |
11 | | -git clone https://github.com/secureCodeBox/securecodebox.github.io.git |
12 | | -cd securecodebox.github.io |
13 | | -npm install |
14 | | -``` |
15 | | - |
16 | | -Done! :) Now you can start developing and contributing. |
17 | | - |
18 | | -For development: |
19 | | - |
20 | | -```bash |
21 | | -npm run develop |
22 | | -``` |
23 | | - |
24 | | -For production locally: |
25 | | - |
26 | | -```bash |
27 | | -npm run build |
28 | | -npm run serve |
29 | | -``` |
30 | | - |
31 | | -And then visit [this](http://localhost:8000/) in your browser. |
32 | | - |
33 | | -## Style Guide |
34 | | - |
35 | | -The overall design-idea is a clean and professional look. And since securecodebox.io serves mostly an informational purpose, it should stay more simplistic than extraordinary, meaning include only information and elements which either are necessary or helpful and very few basic elements for a good look (e.g. fitting background picture). The development started off from this template theme: [gatsbyserif](https://gatsby-serif.netlify.com/). |
36 | | - |
37 | | -### Colors |
38 | | - |
39 | | -The color scheme is aimed to be basically white with a soft blue coloring as the main color and gentle highlighting. This website should not be monochrome or monotonous, so feel free to include colored elements and icons but use different colors only ever so slightly and avoid strong contrasts. |
40 | | - |
41 | | -Included colors: |
42 | | - |
43 | | -``` |
44 | | -$white: #ffffff; |
45 | | -$black: #000000; |
46 | | -$primary: #1c3ed3; // Strong blue tone |
47 | | -$iteragenta: #a9218e; // iteratec's main color (avoid using it ;) ) |
48 | | -$highlight: #7c00ce57; // Gentle, half transparent violet-ish for highlighting |
49 | | -$secureCodeBlue: #3296dc; // Main, soft blue tone |
50 | | -$secondary: #414156; // Grey, used for non-header text |
51 | | -``` |
52 | | - |
53 | | -If new colors will be used standardized, make sure to include them as a variable and list it here with it's purpose. |
54 | | - |
55 | | -### Fonts |
56 | | - |
57 | | -Fonts should be simple and readable. Nothing fancy or special and not be web loaded. |
58 | | - |
59 | | -Used Fonts: |
60 | | - |
61 | | -``` |
62 | | --apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, |
63 | | - Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', |
64 | | - 'Segoe UI Symbol'; |
65 | | -``` |
66 | | - |
67 | | -### Icons & Images |
68 | | - |
69 | | -The icons of the integrations should be monochrome. It is important to have an icon which corresponds to the integrations original icon, but does not need to be the same (we do not want to copy the original one's due to licenses). Colored icons should have on the one side, a generally coherent look on the respective page and on the other side, not stand out from the websites blueish theme. Icons should be free licensed or from [flaticon]. [flaticon] is a great source of millions of free icons and it is referenced on the website for it's use already. Images should be fitting and mainly used as background (partially). They should fit the color scheme if possible or do **not** stand out through a high contrast to the website. Currently we use svg images from [undraw](https://undraw.co/) as background images. In the case you are going to use a png, jpg or jpeg, and it does not load in an instant, use gatsby-image and fluid to avoid a spontaneously popping image, e.g.: |
70 | | - |
71 | | -Query the image on the page: |
72 | | - |
73 | | -```javascript |
74 | | -export const query = graphql` |
75 | | - query { |
76 | | - ImageHomeQuery: file(relativePath: { eq: "images/<ImageName.any>" }) { |
77 | | - childImageSharp { |
78 | | - # Specify the image processing specifications right in the query. |
79 | | - fluid { |
80 | | - ...GatsbyImageSharpFluid |
81 | | - } |
82 | | - } |
83 | | - } |
84 | | - } |
85 | | -`; |
86 | | -``` |
87 | | - |
88 | | -And use the `<Img/>` component: |
89 | | - |
90 | | -```html |
91 | | -<div className="background-plane"> |
92 | | - <img |
93 | | - fluid="{props.data.ImageHomeQuery.childImageSharp.fluid}" |
94 | | - alt="secureCodeBox preview" |
95 | | - objectFit="cover" |
96 | | - className="background-image" |
97 | | - /> |
98 | | -</div> |
99 | | -``` |
100 | | - |
101 | | -Of course you can use this not only for background images, just ignore then everything related to to background in the example. However, currently, the intro style class provides basic styling for the background images. |
102 | | - |
103 | | -Recommended websites for free icons or images: |
104 | | - |
105 | | -- [flaticon](https://www.flaticon.com/) |
106 | | -- [iconmonstr](https://iconmonstr.com/) |
107 | | -- [pixabay](https://pixabay.com/) |
108 | | -- [undraw](https://undraw.co/) |
109 | | - |
110 | | -## Documentation Guide |
111 | | - |
112 | | -Since we work with various different tools, it is even more important to keep a clean and well structured Documentation. Our website's purpose is to provide a comfortable navigation and clear overview. But since no one is going to update the documentation if it's untraceable, it is also very important to keep the documentation's location clear and as less spread as possible throughout our project. So no single-page documentation hidden in the deep structure of a remote repository! In general it is much easier and simpler to keep most of the documentation in this repository, but the scanner documentation due to our project structure. One key feature our documentations share in order to be put on the website is a frontmatter in each documentation. It is mandatory since at least a title and path are required. But it also can provide helpful other information very easily, for a documentation see [frontmatter]. Don't be afraid to use it for including important information, which you can't get/provide otherwise very well, but don't overuse it! For more detailed examples see the following sections. |
113 | | - |
114 | | -### Adding a scanner or persistence provider |
115 | | - |
116 | | -Scanners and persistence providers are referred to as integrations. Scanners, which are integrated into our [secureCodeBox-v2-alpha](https://github.com/secureCodeBox/secureCodeBox-v2-alpha) repository have their own directories (located at [/scanners/](https://github.com/secureCodeBox/secureCodeBox-v2-alpha/tree/master/scanners)) in which the main documentation must be written in a `README.md` file. Persistence provider documentation is located at `/src/pages/integrations/persistence-provider/`. |
117 | | - |
118 | | -#### Scanner |
119 | | - |
120 | | -To add a scanner documentation you need to extend the `scannerRepos` Array in the `gatsby-config.js` file with: |
121 | | - |
122 | | -```bash |
123 | | - { |
124 | | - name: 'scanner name', |
125 | | - directory: 'directoryName' # in /scanners/ |
126 | | - } |
127 | | -``` |
128 | | - |
129 | | -Additionally you can and (for the sake of aesthetics) should provide an icon in `.svg` format (the fancy icons you see on the "Integrations" page), located at `/src/static/integrationIcons`. Simply name it according to the title in the frontmatter, e.g. if the scanner's title is "Arachni" your filename is "Arachni.svg", it's as simple as that. Each of our scanner has a release svg, which needs to be put in the frontmatter of the respective documentation. Our scanner are structured uniformly with a frontmatter of mandatory fields as follows ("Scame" represents the scanner name): |
130 | | - |
131 | | -<details> |
132 | | -<summary>Scanner documentation structure</summary> |
133 | | -<br> |
134 | | -<pre> |
135 | | - |
136 | | - --- |
137 | | - |
138 | | - title: "Scame" |
139 | | - path: "scanner/Scame" |
140 | | - category: "scanner" |
141 | | - usecase: "general use of this scanner" |
142 | | - |
143 | | - --- |
144 | | - |
145 | | -  //not required but nice to have |
146 | | - |
147 | | - A brief description about this scanner. |
148 | | - |
149 | | - <!-- end --> |
150 | | - |
151 | | - # About |
152 | | - |
153 | | - This repository contains a self contained µService utilizing the Scame scanner for the secureCodeBox project. To learn more about the Scame scanner itself visit [reference the scanner]. |
154 | | - |
155 | | - ## Scame parameters |
156 | | - |
157 | | - To hand over supported parameters through api usage, you can set following attributes: |
158 | | - |
159 | | - ``` |
160 | | - [ |
161 | | - { |
162 | | - specify parameter and how to configure the scanner |
163 | | - } |
164 | | - ] |
165 | | - ``` |
166 | | - |
167 | | - ## Example |
168 | | - Provide a simple scan example which everyone can simply reconstruct. Give a Example input/configuration and the according output. |
169 | | - |
170 | | - ## Development |
171 | | - |
172 | | - ### Configuration Options |
173 | | - |
174 | | - To configure this service specify the following environment variables: |
175 | | - |
176 | | - | Environment Variable | Value Example | |
177 | | - | -------------------------- | ------------- | |
178 | | - | ENGINE_ADDRESS | http://engine | |
179 | | - | ENGINE_BASIC_AUTH_USER | username | |
180 | | - | ENGINE_BASIC_AUTH_PASSWORD | 123456 | |
181 | | - |
182 | | - ### Local setup |
183 | | - |
184 | | - How to set up the scanner locally. |
185 | | - |
186 | | - ### Test |
187 | | - |
188 | | - How to run the test. |
189 | | - |
190 | | - ### Build with docker |
191 | | - |
192 | | - How to build the docker container. |
193 | | - |
194 | | - |
195 | | - >Travis build status |
196 | | - >License |
197 | | - >GitHub latest release of our Scame repository |
198 | | - |
199 | | - [reference the scanner]: url |
200 | | - |
201 | | -</pre> |
202 | | -</details> |
203 | | - |
204 | | -You can add and extend categories as you will, but keep the main structure and if one section would be empty, write an explanation why, if it's not obvious. See this as a adjustable template and have a look at what is written in the other scanner's docs. |
205 | | - |
206 | | -#### Persistence provider |
207 | | - |
208 | | -To add a persistence provider documentation simply add the markdown file to the folder mentioned above. To provide an icon do as explained before for the scanner. Our persistence provider are structured uniformly with a frontmatter of mandatory fields as follows ("Perprame" represents the persistence provider name): |
209 | | - |
210 | | -<details> |
211 | | -<summary>Persistence provider documentation structure</summary> |
212 | | -<br> |
213 | | -<pre> |
214 | | - |
215 | | - --- |
216 | | - |
217 | | - title: "Perprame" |
218 | | - path: "persistence-provider/Perprame" |
219 | | - category: "persistence provider" |
220 | | - |
221 | | - --- |
222 | | - |
223 | | - ## About |
224 | | - |
225 | | - A brief description of this persistence provider with reference: [Perprame]. |
226 | | - |
227 | | - ## Configuration |
228 | | - |
229 | | - ### Setting the Persistence Provider |
230 | | - |
231 | | - The engine supports multiple different persistence providers. Each of the prepackaged persistence providers can be toggled on by using environment variables. |
232 | | - |
233 | | - The currently available persistence providers are: |
234 | | - |
235 | | - | Name | Environment Variable | Default Value | |
236 | | - | ------------- | ------------------------------------------------- | ------------- | |
237 | | - | Perprame | `SECURECODEBOX_PERSISTENCE_PERPRAME_ENABLED` | `"false"` | |
238 | | - | Elasticsearch | `SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_ENABLED` | `"false"` | |
239 | | - | DefectDojo | `SECURECODEBOX_PERSISTENCE_DEFECTDOJO_ENABLED` | `"false"` | |
240 | | - | S3 | `SECURECODEBOX_PERSISTENCE_S3_ENABLED` | `"false"` | |
241 | | - | None | `SECURECODEBOX_PERSISTENCE_NONE_ENABLED` | `"false"` | |
242 | | - |
243 | | - To activate the persistence providers the `enabled` variable must be set to `"true"`. |
244 | | - |
245 | | - > **Note**: Most PersistenceProviders require additional configuration to set the location and access credentials. These are documented in the sections for the individual persistence providers below. |
246 | | - |
247 | | - The corresponding PersistenceProvider-implementation class must have a matching `@ConditionalOnProperty` annotation, e.g. `@ConditionalOnProperty(name = "securecodebox.persistence.perprame.enabled", havingValue = "true")` for Perprame. |
248 | | - |
249 | | - ## Specific Settings |
250 | | - |
251 | | - #### Enabling Perprame as Persistence Provider |
252 | | - |
253 | | - To use Perprame for persistence set `securecodebox.persistence.perprame.enabled` or the corresponding environment variable to `"true"`. |
254 | | - |
255 | | - #### Properties / Environment Variables |
256 | | - |
257 | | - | Property | Example Value | Mandatory | |
258 | | - | -------- | ------------- | --------- | |
259 | | - | | | | |
260 | | - |
261 | | - |
262 | | - [Perprame]: reference url |
263 | | - |
264 | | -</pre> |
265 | | -</details> |
266 | | - |
267 | | -### Adding tutorials or developer docs |
268 | | - |
269 | | -Currently under development, please provide an explanation to why these are split and how this differentiation is meant. |
270 | | - |
271 | | -#### Tutorials |
272 | | - |
273 | | -Currently under development, this will be the guide for our "Get Started" tutorials similar to the ones above. |
274 | | - |
275 | | -#### Developer docs |
276 | | - |
277 | | -Currently under development, this will be the guide for our "Docs" developer documentation similar to the ones above. |
278 | | - |
279 | | -## Production Deployment |
280 | | - |
281 | | -All changes pushed to the `gh-source` branch get automatically build by GitHub Actions. |
282 | | -The artifacts of the build, aka. the build site, gets forced pushed to the master branch. |
283 | | -The master branch then gets automatically deployed as a GitHub Page. |
284 | | - |
285 | | -[securecodebox.io]: https://securecodebox.github.io |
286 | | -[securecodebox]: https://github.com/secureCodeBox/secureCodeBox |
287 | | -[gatsbyjs]: https://www.gatsbyjs.org/ |
288 | | -[github pages]: https://pages.github.com/ |
289 | | -[node.js and npm]: https://nodejs.org/en/download/ |
290 | | -[frontmatter]: https://www.gatsbyjs.org/docs/adding-markdown-pages/#frontmatter-for-metadata-in-markdown-files |
| 3 | +This repository sources the <https://www.securecodebox.io> website. |
0 commit comments